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

//

/** 

@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