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

 // Hardware Configuration Respoitory Platform Independent Layer (PIL)

 // Contains the hardware abstraction interface implemented in the variant PSL

 // HCR kernel extension project.

 //

 /** 

 @file hcr_hai.h

 Kernel side definitions for the HCR Symbian Hardware Abstraction 

 Interface (SHAI) for variants to implement when creating a HCR.dll binary.

 @publishedPartner

 @prototype

 */

 #ifndef HCR_HAI_H

 #define HCR_HAI_H

 // -- INCLUDES ----------------------------------------------------------------

 #include <e32def.h>

 #include <e32err.h> 

 #include <drivers/hcr.h>

 // -- CLASSES -----------------------------------------------------------------

 /**

 The HCR namespace contains all the types and classes that make up the

 Kernel side Hardware Configuration Repository (HCR).

 */

 namespace HCR

     {

 	/** Constant defined for the first HCR repository format. Used for both 

 	compiled and file repositories. 	

 	@see SRepositoryBase::iFormatVersion	

 	*/	    

     static const TInt KRepositoryFirstVersion = 0x0001;

     /** Interface class defining the methods variants must implement to provide

     a complete HCR component for the targeted variant.  

     The HCR supports three repositories and it is recommended that as few of 

     these are employed for a variant to minimise lookup overheads as setting 

     override flexibility is provided at the expense of lookup performance.       

     */

     class MVariant

         {

     public:

         /** 

         Perform platform specific initialisation of variant HCR object. Invoked 

         during HCR kernel extension module initialisation. 

         Note: an error code from this method will prevent device startup.

     	@return	KErrNone if successful, or any other system wide error code.

         */    

         virtual TInt Initialise() = 0;

     	/**

         This method returns the address of the compile time setting repository 

         built into the variant HCR.dll project/binary. This repository is 

         optional and may be absent in which case 0 should be returned in aAddr. 

         @param aAddr out: a pointer to a HCR::SRepositoryCompiled 

     	@return	KErrNone if successful, output parameters valid,

     	        KErrNotSupported if a compile time repository is not supported,

     	        Any other system wide error code.

         @see HCR::SRepositoryCompiled

        	*/

         virtual TInt GetCompiledRepositoryAddress(TAny* & aAddr) = 0;

    	    /**

         This method is called at kernel initialisation and allows the PSL to 

 		disable the initial lookup of the built-in Core Image file repository. 

 		The PSL should return ETrue if the device/BSP is not going to support 

 		this repository. 	

     	@return	ETrue if the PIL should not find the repository in the ROM

     	        EFalse if the core image repository is to be used/supported

        	*/

         virtual TBool IgnoreCoreImgRepository () = 0;

     	/**

         This method returns the address of the override repository that 

         provides override values for the variant. Typically this repository

         is held in NAND flash and shadowed in RAM by the OS loader. It is

         a read-only settings repository. This repository is optional and may 

         be absent in which case 0 should be returned in aAddr.

         @param aAddr out: a pointer to a HCR::SRepositoryFile

     	@return	KErrNone if successful, output parameters valid,

     	        KErrNotSupported if a compile time repository is not supported,

     	        Any other system wide error code.

         @see HCR::SRepositoryFile

        	*/

         virtual TInt GetOverrideRepositoryAddress(TAny* & aAddr) = 0;

         };       

     /** Union that holds one of the supported word-sized setting values 

     */

     union UValueWord

         {

         TInt32      iInt32;

         TInt16      iInt16;

         TInt8       iInt8;

         TBool       iBool;

         TUint32     iUInt32;

         TUint16     iUInt16;

         TUint8      iUInt8;

         TLinAddr    iAddress;

         };

     /** Union that holds a pointer to one of the supported large value types 

     */

     union UValueLarge

         {

         TUint8*     iData;          //!< Array of TUint8 values

         TText8*     iString8;       //!< Array of TText8 values

 		TInt32*		iArrayInt32;	//!< Array of TInt32 values

 		TUint32*	iArrayUInt32;	//!< Array of TUInt32 values

         TInt64*     iInt64;         //!< Single TInt64 value

         TUint64*    iUInt64;        //!< Single TUint64 value

         };

     /** Type used to hold the offset to a large setting value */

     typedef TInt TValueLargeOffset;

     /** Union type used to hold either the literal value or a C++ pointer to 

     the value. Used in compile time settings.   

     */

     union USettingValueC

         {

         UValueWord  iLit;

         UValueLarge iPtr;

         };

     /** Union type used to hold either the literal value or an offset from the 

     start if the setting repository to the setting value. Used in file and RAM

     mapped settings.   

     */

     union USettingValueF

         {

         UValueWord          iLit;

         TValueLargeOffset   iOffset;

         };

     /** Metadata flags to describe properties of the settings.

     */

     enum TSettingProperties

         {

         EPropUndefined     = 0x0000,   //!< Unknown/not set

         // Following properties are not yet supported:

         EPropUnintiailised = 0x0001,   //!< Setting has no initial value

         EPropModifiable    = 0x0002,   //!< Setting is set/writable

         EPropPersistent    = 0x0004,   //!< Setting is non-volatile

         // Following properties are not yet supported but are envisaged to be

 		// implemented to support setting breaks/migration where settings 

 		// evolve and/or replace each other.

         EPropDeprecated	   = 0x1000,   //!< Setting supported but deprecate, accessed logged

 		EPropReplaced      = 0x2000,   //!< HCR redirected to retrieve value from replacement setting, access logged

 		EPropWithdrawn	   = 0x4000    //!< Setting withdrawn, log & panic if accessed 

         };        

     /** Provides base class for setting records. All setting structures start

     with this structure providing common setting attributes such as the

     identifier, type etc.    

     */

     struct SSettingBase

         {

         SSettingId  iId;        // Always the first member!

         TInt32      iType;      //!< @see TSettingType

         TUint16     iFlags;     //!< @See TSettingProperties

         TUint16     iLen;       //!< Only valid if setting is a large type

         };

     /** This structure holds a setting defined at compile time within a compile

     time defined repository.     

     @see SRepositoryCompiled

     */

     struct SSettingC            // : public SSettingBase

         {

         SSettingBase    iName;  // Always the first member!

         USettingValueC  iValue;

         };

     /** This structure holds a setting define in a file or memory within a file

     based repository.     

     @see SRepositoryFile

     */

     struct SSettingF             // : public SSettingBase

         {

         SSettingBase    iName;   // Always the first member!

         USettingValueF  iValue;

         };

     /** Metadata flags to describe the repository type/layout.

     */

     enum TRepositoryType

         {

         EReposUndefined = 0x00,   //!< Unknown

         EReposCompiled  = 'c',   //!< Repository is in Compiled layout

         EReposFile      = 'f'    //!< Repository is in File layout

         };        

     /** Metadata flags to describe repository properties.

     */

     enum TRepositoryProperties

         {

         EReposClear       = 0x0000,   //!< Unknown

         EReposReadOnly    = 0x0001,   //!< Repository is read-only

         EReposNonVolatile = 0x0002    //!< Repository is writable, saved to flash

         };        

     /** Provides base class for setting repositories. All repository structures 

     start with this structure providing common repository attributes such as the

     type , size etc.   

     */

     struct SRepositoryBase

         {

         TUint8      iFingerPrint[3];    //!< Fixed value {'H', 'C', 'R'}

         TUint8      iType;              //!< @See TRepositoryType

         TInt16      iFormatVersion;     //!< Format/layout version number

         TUint16     iFlags;             //!< @see TRepositoryProperties

         TInt32      iNumSettings;       //!< Number of settings in repository

         };    

     /** This class is the root object for a compile time defined settings 

     repository and is used in the PSL HCR variant object to hold read-only

     compile time settings. This type of repository makes use of pointers to 

     structures and arrays as it is compiled.

     */

     struct SRepositoryCompiled

         {

         SRepositoryBase*    iHdr;        // Always the first member!

         SSettingC*          iOrderedSettingList;

         };    

     /** Byte type for large setting value data 

     */

     typedef TUint8 TSettingData;

     /** This class is the root object for a file or memory based settings 

     repository. It assumes the repository has a flat contiguous layout and

     employees offsets to data rather then C++ pointers as in compiled 

     setting repositories.                 

     All offsets are relative to the address of &iHdr member.

     The last two members are expected to be present in the file/memory as shown

     although there is no way at type definition time to know the size of these

     members, hence they are commented out and will be accessed in the code

     using memory/file address arithmetic.

     */

     struct SRepositoryFile 

         {

         SRepositoryBase     iHdr;        // Always the first member!

         TUint32             iLSDfirstByteOffset;

 		TUint32             iLSDataSize;

 		TUint32				iReserved[3];

      // SSettingF           iOrderedSettingList[iNumSettings];

      // TSettingData        iLargeSettingsData[iLSDataSize];

         };    

     }

 // -- GLOBALS -----------------------------------------------------------------

 /**

 Global entry point used by PIL to create the variant HCR object in the PSL

 code.

 @return Pointer to variant is successfully, 0 otherwise.

 @see HCR::MVariant

 */

 GLREF_C HCR::MVariant* CreateHCRVariant(); 

 // -- MACROS ------------------------------------------------------------------

 /** 

 Global macro for use in defining the finger print field of a 

 SRepositoryCompiled.iHdr instance in the PSL compiled repository static data.

 Macro used in PSL source as the value for the finger print field in a

 compiled repository.

 @see SRepositoryBase::iFingerPrint

 */

 #define HCR_FINGER_PRINT {'H', 'C', 'R'}

 /** 

 Global macro for use in defining the finger print field of a 

 SRepositoryCompiled.iHdr instance in the PSL compiled repository static data.

 Macro used in PSL source as the value for the finger print field in a

 compiled repository.

 @see SRepositoryBase::iFingerPrint

 */

 #define HCR_SETTING_COUNT(a) (sizeof(a)/sizeof(SSettingC))

 /**

 Global macro for use in setting the flags attribute of a SSettingC 

 instance in the PSL compiled repository static data.

 @see HCR::MVariant

 @see HCR::SRepositoryCompiled

 */

 #define HCR_FLAGS_NONE		HCR::EPropUndefined

 /**

 Global macro for use in setting the length attribute of a SSettingC 

 instance in the PSL compiled repository static data.

 @see HCR::MVariant

 @see HCR::SRepositoryCompiled

 */

 #define HCR_LEN_NA			0x0000

 /**

 Global macro for use in defining the actual integer (word) value of a SettingC 

 instance in the PSL compiled repository static data. This can be used to 

 simplify the setting table for settings with the type flag

 set to one of 0x0000FFFF.

 @see HCR::MVariant

 @see HCR::SRepositoryCompiled

 */

 #define HCR_WVALUE(a)	static_cast<TInt32>(a)

 /**

 Global macro for use in assigning the address of a large setting value to an 

 instance of a SettingC in the PSL compiled repository static data. This can be 

 used to simplify the setting table for settings with the type flag

 set to one of 0xFFFF0000.

 @see HCR::MVariant

 @see HCR::SRepositoryCompiled

 */

 #define HCR_LVALUE(a)	reinterpret_cast<TInt32>(a)

 /**

 Global macro used as last entry in a PSL compiled repository static data. 

 The main use of this is to avoid the "last entry needs no following comma" issue

 and to aid HCR initial thead testing. 

 The Setting (0xffffffff, 0xffffffff) was choosen as it should never appear in

 a real variant as this category UID can not be allocated offically. Testers

 should also be aware of the special use of this setting so as not to use it in

 a file repository.

 @see HCR::MVariant

 @see HCR::SRepositoryCompiled

 */

 #define HCR_LAST_SETTING { { { 0xFFFFFFFF, 0xFFFFFFFF}, ETypeUInt32, HCR_FLAGS_NONE, HCR_LEN_NA }, { { 0x4C415354 }}}

 #endif // HCR_HAI_H