diff -r 000000000000 -r a41df078684a kernel/eka/drivers/hcr/hcr_hai.h --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/kernel/eka/drivers/hcr/hcr_hai.h Mon Oct 19 15:55:17 2009 +0100 @@ -0,0 +1,326 @@ +// 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 Hardware Abstraction Interface for variants +to implement when creating a HCR.dll binary. + + +=============================================================== + ____ _ _ +| _ \ _ __ ___ | |_ ___ | |_ _ _ _ __ ___ +| |_) | '__/ _ \| __/ _ \| __| | | | '_ \ / _ \ +| __/| | | (_) | || (_) | |_| |_| | |_) | __/ +|_| |_| \___/ \__\___/ \__|\__, | .__/ \___| + |___/|_| + +This API and component are in an early release form. As such +this component, it's API/HAI interfaces and internal design +are not fixed and may be updated/changed at any time before +final release. + +=============================================================== + + +@publishedPartner +@prototype +*/ + +#ifndef HCR_HAI_H +#define HCR_HAI_H + + +// -- INCLUDES ---------------------------------------------------------------- + + +#include +#include + +#include + +/** 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'} + + +// -- 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(); + + + +#endif // HCR_HAI_H