sl@0: // Copyright (c) 2008-2009 Nokia Corporation and/or its subsidiary(-ies). sl@0: // All rights reserved. sl@0: // This component and the accompanying materials are made available sl@0: // under the terms of the License "Eclipse Public License v1.0" sl@0: // which accompanies this distribution, and is available sl@0: // at the URL "http://www.eclipse.org/legal/epl-v10.html". sl@0: // sl@0: // Initial Contributors: sl@0: // Nokia Corporation - initial contribution. sl@0: // sl@0: // Contributors: sl@0: // sl@0: // Description: sl@0: // Hardware Configuration Respoitory Platform Independent Layer (PIL) sl@0: // Contains the hardware abstraction interface implemented in the variant PSL sl@0: // HCR kernel extension project. sl@0: // sl@0: sl@0: /** sl@0: @file hcr_hai.h sl@0: Kernel side definitions for the HCR Symbian Hardware Abstraction sl@0: Interface (SHAI) for variants to implement when creating a HCR.dll binary. sl@0: sl@0: @publishedPartner sl@0: @prototype sl@0: */ sl@0: sl@0: #ifndef HCR_HAI_H sl@0: #define HCR_HAI_H sl@0: sl@0: sl@0: // -- INCLUDES ---------------------------------------------------------------- sl@0: sl@0: sl@0: #include sl@0: #include sl@0: sl@0: #include sl@0: sl@0: sl@0: // -- CLASSES ----------------------------------------------------------------- sl@0: sl@0: sl@0: /** sl@0: The HCR namespace contains all the types and classes that make up the sl@0: Kernel side Hardware Configuration Repository (HCR). sl@0: */ sl@0: namespace HCR sl@0: { sl@0: /** Constant defined for the first HCR repository format. Used for both sl@0: compiled and file repositories. sl@0: @see SRepositoryBase::iFormatVersion sl@0: */ sl@0: static const TInt KRepositoryFirstVersion = 0x0001; sl@0: sl@0: /** Interface class defining the methods variants must implement to provide sl@0: a complete HCR component for the targeted variant. sl@0: The HCR supports three repositories and it is recommended that as few of sl@0: these are employed for a variant to minimise lookup overheads as setting sl@0: override flexibility is provided at the expense of lookup performance. sl@0: */ sl@0: class MVariant sl@0: { sl@0: public: sl@0: sl@0: /** sl@0: Perform platform specific initialisation of variant HCR object. Invoked sl@0: during HCR kernel extension module initialisation. sl@0: Note: an error code from this method will prevent device startup. sl@0: sl@0: @return KErrNone if successful, or any other system wide error code. sl@0: */ sl@0: virtual TInt Initialise() = 0; sl@0: sl@0: sl@0: /** sl@0: This method returns the address of the compile time setting repository sl@0: built into the variant HCR.dll project/binary. This repository is sl@0: optional and may be absent in which case 0 should be returned in aAddr. sl@0: sl@0: @param aAddr out: a pointer to a HCR::SRepositoryCompiled sl@0: @return KErrNone if successful, output parameters valid, sl@0: KErrNotSupported if a compile time repository is not supported, sl@0: Any other system wide error code. sl@0: @see HCR::SRepositoryCompiled sl@0: */ sl@0: virtual TInt GetCompiledRepositoryAddress(TAny* & aAddr) = 0; sl@0: sl@0: /** sl@0: This method is called at kernel initialisation and allows the PSL to sl@0: disable the initial lookup of the built-in Core Image file repository. sl@0: The PSL should return ETrue if the device/BSP is not going to support sl@0: this repository. sl@0: sl@0: @return ETrue if the PIL should not find the repository in the ROM sl@0: EFalse if the core image repository is to be used/supported sl@0: */ sl@0: virtual TBool IgnoreCoreImgRepository () = 0; sl@0: sl@0: /** sl@0: This method returns the address of the override repository that sl@0: provides override values for the variant. Typically this repository sl@0: is held in NAND flash and shadowed in RAM by the OS loader. It is sl@0: a read-only settings repository. This repository is optional and may sl@0: be absent in which case 0 should be returned in aAddr. sl@0: sl@0: @param aAddr out: a pointer to a HCR::SRepositoryFile sl@0: @return KErrNone if successful, output parameters valid, sl@0: KErrNotSupported if a compile time repository is not supported, sl@0: Any other system wide error code. sl@0: @see HCR::SRepositoryFile sl@0: */ sl@0: virtual TInt GetOverrideRepositoryAddress(TAny* & aAddr) = 0; sl@0: sl@0: }; sl@0: sl@0: sl@0: /** Union that holds one of the supported word-sized setting values sl@0: */ sl@0: union UValueWord sl@0: { sl@0: TInt32 iInt32; sl@0: TInt16 iInt16; sl@0: TInt8 iInt8; sl@0: TBool iBool; sl@0: TUint32 iUInt32; sl@0: TUint16 iUInt16; sl@0: TUint8 iUInt8; sl@0: TLinAddr iAddress; sl@0: }; sl@0: sl@0: /** Union that holds a pointer to one of the supported large value types sl@0: */ sl@0: union UValueLarge sl@0: { sl@0: TUint8* iData; //!< Array of TUint8 values sl@0: TText8* iString8; //!< Array of TText8 values sl@0: TInt32* iArrayInt32; //!< Array of TInt32 values sl@0: TUint32* iArrayUInt32; //!< Array of TUInt32 values sl@0: TInt64* iInt64; //!< Single TInt64 value sl@0: TUint64* iUInt64; //!< Single TUint64 value sl@0: }; sl@0: sl@0: /** Type used to hold the offset to a large setting value */ sl@0: typedef TInt TValueLargeOffset; sl@0: sl@0: /** Union type used to hold either the literal value or a C++ pointer to sl@0: the value. Used in compile time settings. sl@0: */ sl@0: union USettingValueC sl@0: { sl@0: UValueWord iLit; sl@0: UValueLarge iPtr; sl@0: }; sl@0: sl@0: /** Union type used to hold either the literal value or an offset from the sl@0: start if the setting repository to the setting value. Used in file and RAM sl@0: mapped settings. sl@0: */ sl@0: union USettingValueF sl@0: { sl@0: UValueWord iLit; sl@0: TValueLargeOffset iOffset; sl@0: }; sl@0: sl@0: /** Metadata flags to describe properties of the settings. sl@0: */ sl@0: enum TSettingProperties sl@0: { sl@0: EPropUndefined = 0x0000, //!< Unknown/not set sl@0: sl@0: // Following properties are not yet supported: sl@0: EPropUnintiailised = 0x0001, //!< Setting has no initial value sl@0: EPropModifiable = 0x0002, //!< Setting is set/writable sl@0: EPropPersistent = 0x0004, //!< Setting is non-volatile sl@0: sl@0: // Following properties are not yet supported but are envisaged to be sl@0: // implemented to support setting breaks/migration where settings sl@0: // evolve and/or replace each other. sl@0: EPropDeprecated = 0x1000, //!< Setting supported but deprecate, accessed logged sl@0: EPropReplaced = 0x2000, //!< HCR redirected to retrieve value from replacement setting, access logged sl@0: EPropWithdrawn = 0x4000 //!< Setting withdrawn, log & panic if accessed sl@0: }; sl@0: sl@0: /** Provides base class for setting records. All setting structures start sl@0: with this structure providing common setting attributes such as the sl@0: identifier, type etc. sl@0: */ sl@0: struct SSettingBase sl@0: { sl@0: SSettingId iId; // Always the first member! sl@0: TInt32 iType; //!< @see TSettingType sl@0: TUint16 iFlags; //!< @See TSettingProperties sl@0: TUint16 iLen; //!< Only valid if setting is a large type sl@0: }; sl@0: sl@0: /** This structure holds a setting defined at compile time within a compile sl@0: time defined repository. sl@0: @see SRepositoryCompiled sl@0: */ sl@0: struct SSettingC // : public SSettingBase sl@0: { sl@0: SSettingBase iName; // Always the first member! sl@0: USettingValueC iValue; sl@0: }; sl@0: sl@0: /** This structure holds a setting define in a file or memory within a file sl@0: based repository. sl@0: @see SRepositoryFile sl@0: */ sl@0: struct SSettingF // : public SSettingBase sl@0: { sl@0: SSettingBase iName; // Always the first member! sl@0: USettingValueF iValue; sl@0: }; sl@0: sl@0: sl@0: /** Metadata flags to describe the repository type/layout. sl@0: */ sl@0: enum TRepositoryType sl@0: { sl@0: EReposUndefined = 0x00, //!< Unknown sl@0: sl@0: EReposCompiled = 'c', //!< Repository is in Compiled layout sl@0: EReposFile = 'f' //!< Repository is in File layout sl@0: }; sl@0: sl@0: /** Metadata flags to describe repository properties. sl@0: */ sl@0: enum TRepositoryProperties sl@0: { sl@0: EReposClear = 0x0000, //!< Unknown sl@0: EReposReadOnly = 0x0001, //!< Repository is read-only sl@0: EReposNonVolatile = 0x0002 //!< Repository is writable, saved to flash sl@0: }; sl@0: sl@0: /** Provides base class for setting repositories. All repository structures sl@0: start with this structure providing common repository attributes such as the sl@0: type , size etc. sl@0: */ sl@0: struct SRepositoryBase sl@0: { sl@0: TUint8 iFingerPrint[3]; //!< Fixed value {'H', 'C', 'R'} sl@0: TUint8 iType; //!< @See TRepositoryType sl@0: TInt16 iFormatVersion; //!< Format/layout version number sl@0: TUint16 iFlags; //!< @see TRepositoryProperties sl@0: TInt32 iNumSettings; //!< Number of settings in repository sl@0: }; sl@0: sl@0: sl@0: /** This class is the root object for a compile time defined settings sl@0: repository and is used in the PSL HCR variant object to hold read-only sl@0: compile time settings. This type of repository makes use of pointers to sl@0: structures and arrays as it is compiled. sl@0: */ sl@0: struct SRepositoryCompiled sl@0: { sl@0: SRepositoryBase* iHdr; // Always the first member! sl@0: SSettingC* iOrderedSettingList; sl@0: }; sl@0: sl@0: sl@0: /** Byte type for large setting value data sl@0: */ sl@0: typedef TUint8 TSettingData; sl@0: sl@0: /** This class is the root object for a file or memory based settings sl@0: repository. It assumes the repository has a flat contiguous layout and sl@0: employees offsets to data rather then C++ pointers as in compiled sl@0: setting repositories. sl@0: All offsets are relative to the address of &iHdr member. sl@0: The last two members are expected to be present in the file/memory as shown sl@0: although there is no way at type definition time to know the size of these sl@0: members, hence they are commented out and will be accessed in the code sl@0: using memory/file address arithmetic. sl@0: */ sl@0: struct SRepositoryFile sl@0: { sl@0: SRepositoryBase iHdr; // Always the first member! sl@0: TUint32 iLSDfirstByteOffset; sl@0: TUint32 iLSDataSize; sl@0: TUint32 iReserved[3]; sl@0: // SSettingF iOrderedSettingList[iNumSettings]; sl@0: // TSettingData iLargeSettingsData[iLSDataSize]; sl@0: }; sl@0: sl@0: } sl@0: sl@0: sl@0: // -- GLOBALS ----------------------------------------------------------------- sl@0: sl@0: sl@0: /** sl@0: Global entry point used by PIL to create the variant HCR object in the PSL sl@0: code. sl@0: sl@0: @return Pointer to variant is successfully, 0 otherwise. sl@0: @see HCR::MVariant sl@0: */ sl@0: GLREF_C HCR::MVariant* CreateHCRVariant(); sl@0: sl@0: sl@0: sl@0: // -- MACROS ------------------------------------------------------------------ sl@0: sl@0: sl@0: /** sl@0: Global macro for use in defining the finger print field of a sl@0: SRepositoryCompiled.iHdr instance in the PSL compiled repository static data. sl@0: sl@0: Macro used in PSL source as the value for the finger print field in a sl@0: compiled repository. sl@0: @see SRepositoryBase::iFingerPrint sl@0: */ sl@0: #define HCR_FINGER_PRINT {'H', 'C', 'R'} sl@0: sl@0: /** sl@0: Global macro for use in defining the finger print field of a sl@0: SRepositoryCompiled.iHdr instance in the PSL compiled repository static data. sl@0: sl@0: Macro used in PSL source as the value for the finger print field in a sl@0: compiled repository. sl@0: @see SRepositoryBase::iFingerPrint sl@0: */ sl@0: #define HCR_SETTING_COUNT(a) (sizeof(a)/sizeof(SSettingC)) sl@0: sl@0: /** sl@0: Global macro for use in setting the flags attribute of a SSettingC sl@0: instance in the PSL compiled repository static data. sl@0: sl@0: @see HCR::MVariant sl@0: @see HCR::SRepositoryCompiled sl@0: */ sl@0: #define HCR_FLAGS_NONE HCR::EPropUndefined sl@0: sl@0: /** sl@0: Global macro for use in setting the length attribute of a SSettingC sl@0: instance in the PSL compiled repository static data. sl@0: sl@0: @see HCR::MVariant sl@0: @see HCR::SRepositoryCompiled sl@0: */ sl@0: #define HCR_LEN_NA 0x0000 sl@0: sl@0: /** sl@0: Global macro for use in defining the actual integer (word) value of a SettingC sl@0: instance in the PSL compiled repository static data. This can be used to sl@0: simplify the setting table for settings with the type flag sl@0: set to one of 0x0000FFFF. sl@0: sl@0: @see HCR::MVariant sl@0: @see HCR::SRepositoryCompiled sl@0: */ sl@0: #define HCR_WVALUE(a) static_cast(a) sl@0: sl@0: /** sl@0: Global macro for use in assigning the address of a large setting value to an sl@0: instance of a SettingC in the PSL compiled repository static data. This can be sl@0: used to simplify the setting table for settings with the type flag sl@0: set to one of 0xFFFF0000. sl@0: sl@0: @see HCR::MVariant sl@0: @see HCR::SRepositoryCompiled sl@0: */ sl@0: #define HCR_LVALUE(a) reinterpret_cast(a) sl@0: sl@0: /** sl@0: Global macro used as last entry in a PSL compiled repository static data. sl@0: The main use of this is to avoid the "last entry needs no following comma" issue sl@0: and to aid HCR initial thead testing. sl@0: The Setting (0xffffffff, 0xffffffff) was choosen as it should never appear in sl@0: a real variant as this category UID can not be allocated offically. Testers sl@0: should also be aware of the special use of this setting so as not to use it in sl@0: a file repository. sl@0: sl@0: @see HCR::MVariant sl@0: @see HCR::SRepositoryCompiled sl@0: */ sl@0: #define HCR_LAST_SETTING { { { 0xFFFFFFFF, 0xFFFFFFFF}, ETypeUInt32, HCR_FLAGS_NONE, HCR_LEN_NA }, { { 0x4C415354 }}} sl@0: sl@0: sl@0: #endif // HCR_HAI_H