--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/kernel/eka/drivers/hcr/hcr_hai.h Thu Dec 17 09:24:54 2009 +0200
@@ -0,0 +1,380 @@
+// 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