Update contrib.
1 // Copyright (c) 2008-2009 Nokia Corporation and/or its subsidiary(-ies).
2 // All rights reserved.
3 // This component and the accompanying materials are made available
4 // under the terms of the License "Eclipse Public License v1.0"
5 // which accompanies this distribution, and is available
6 // at the URL "http://www.eclipse.org/legal/epl-v10.html".
8 // Initial Contributors:
9 // Nokia Corporation - initial contribution.
14 // Hardware Configuration Respoitory Platform Independent Layer (PIL)
15 // Contains the hardware abstraction interface implemented in the variant PSL
16 // HCR kernel extension project.
21 Kernel side definitions for the HCR Symbian Hardware Abstraction
22 Interface (SHAI) for variants to implement when creating a HCR.dll binary.
32 // -- INCLUDES ----------------------------------------------------------------
38 #include <drivers/hcr.h>
41 // -- CLASSES -----------------------------------------------------------------
45 The HCR namespace contains all the types and classes that make up the
46 Kernel side Hardware Configuration Repository (HCR).
50 /** Constant defined for the first HCR repository format. Used for both
51 compiled and file repositories.
52 @see SRepositoryBase::iFormatVersion
54 static const TInt KRepositoryFirstVersion = 0x0001;
56 /** Interface class defining the methods variants must implement to provide
57 a complete HCR component for the targeted variant.
58 The HCR supports three repositories and it is recommended that as few of
59 these are employed for a variant to minimise lookup overheads as setting
60 override flexibility is provided at the expense of lookup performance.
67 Perform platform specific initialisation of variant HCR object. Invoked
68 during HCR kernel extension module initialisation.
69 Note: an error code from this method will prevent device startup.
71 @return KErrNone if successful, or any other system wide error code.
73 virtual TInt Initialise() = 0;
77 This method returns the address of the compile time setting repository
78 built into the variant HCR.dll project/binary. This repository is
79 optional and may be absent in which case 0 should be returned in aAddr.
81 @param aAddr out: a pointer to a HCR::SRepositoryCompiled
82 @return KErrNone if successful, output parameters valid,
83 KErrNotSupported if a compile time repository is not supported,
84 Any other system wide error code.
85 @see HCR::SRepositoryCompiled
87 virtual TInt GetCompiledRepositoryAddress(TAny* & aAddr) = 0;
90 This method is called at kernel initialisation and allows the PSL to
91 disable the initial lookup of the built-in Core Image file repository.
92 The PSL should return ETrue if the device/BSP is not going to support
95 @return ETrue if the PIL should not find the repository in the ROM
96 EFalse if the core image repository is to be used/supported
98 virtual TBool IgnoreCoreImgRepository () = 0;
101 This method returns the address of the override repository that
102 provides override values for the variant. Typically this repository
103 is held in NAND flash and shadowed in RAM by the OS loader. It is
104 a read-only settings repository. This repository is optional and may
105 be absent in which case 0 should be returned in aAddr.
107 @param aAddr out: a pointer to a HCR::SRepositoryFile
108 @return KErrNone if successful, output parameters valid,
109 KErrNotSupported if a compile time repository is not supported,
110 Any other system wide error code.
111 @see HCR::SRepositoryFile
113 virtual TInt GetOverrideRepositoryAddress(TAny* & aAddr) = 0;
118 /** Union that holds one of the supported word-sized setting values
132 /** Union that holds a pointer to one of the supported large value types
136 TUint8* iData; //!< Array of TUint8 values
137 TText8* iString8; //!< Array of TText8 values
138 TInt32* iArrayInt32; //!< Array of TInt32 values
139 TUint32* iArrayUInt32; //!< Array of TUInt32 values
140 TInt64* iInt64; //!< Single TInt64 value
141 TUint64* iUInt64; //!< Single TUint64 value
144 /** Type used to hold the offset to a large setting value */
145 typedef TInt TValueLargeOffset;
147 /** Union type used to hold either the literal value or a C++ pointer to
148 the value. Used in compile time settings.
156 /** Union type used to hold either the literal value or an offset from the
157 start if the setting repository to the setting value. Used in file and RAM
163 TValueLargeOffset iOffset;
166 /** Metadata flags to describe properties of the settings.
168 enum TSettingProperties
170 EPropUndefined = 0x0000, //!< Unknown/not set
172 // Following properties are not yet supported:
173 EPropUnintiailised = 0x0001, //!< Setting has no initial value
174 EPropModifiable = 0x0002, //!< Setting is set/writable
175 EPropPersistent = 0x0004, //!< Setting is non-volatile
177 // Following properties are not yet supported but are envisaged to be
178 // implemented to support setting breaks/migration where settings
179 // evolve and/or replace each other.
180 EPropDeprecated = 0x1000, //!< Setting supported but deprecate, accessed logged
181 EPropReplaced = 0x2000, //!< HCR redirected to retrieve value from replacement setting, access logged
182 EPropWithdrawn = 0x4000 //!< Setting withdrawn, log & panic if accessed
185 /** Provides base class for setting records. All setting structures start
186 with this structure providing common setting attributes such as the
187 identifier, type etc.
191 SSettingId iId; // Always the first member!
192 TInt32 iType; //!< @see TSettingType
193 TUint16 iFlags; //!< @See TSettingProperties
194 TUint16 iLen; //!< Only valid if setting is a large type
197 /** This structure holds a setting defined at compile time within a compile
198 time defined repository.
199 @see SRepositoryCompiled
201 struct SSettingC // : public SSettingBase
203 SSettingBase iName; // Always the first member!
204 USettingValueC iValue;
207 /** This structure holds a setting define in a file or memory within a file
211 struct SSettingF // : public SSettingBase
213 SSettingBase iName; // Always the first member!
214 USettingValueF iValue;
218 /** Metadata flags to describe the repository type/layout.
222 EReposUndefined = 0x00, //!< Unknown
224 EReposCompiled = 'c', //!< Repository is in Compiled layout
225 EReposFile = 'f' //!< Repository is in File layout
228 /** Metadata flags to describe repository properties.
230 enum TRepositoryProperties
232 EReposClear = 0x0000, //!< Unknown
233 EReposReadOnly = 0x0001, //!< Repository is read-only
234 EReposNonVolatile = 0x0002 //!< Repository is writable, saved to flash
237 /** Provides base class for setting repositories. All repository structures
238 start with this structure providing common repository attributes such as the
241 struct SRepositoryBase
243 TUint8 iFingerPrint[3]; //!< Fixed value {'H', 'C', 'R'}
244 TUint8 iType; //!< @See TRepositoryType
245 TInt16 iFormatVersion; //!< Format/layout version number
246 TUint16 iFlags; //!< @see TRepositoryProperties
247 TInt32 iNumSettings; //!< Number of settings in repository
251 /** This class is the root object for a compile time defined settings
252 repository and is used in the PSL HCR variant object to hold read-only
253 compile time settings. This type of repository makes use of pointers to
254 structures and arrays as it is compiled.
256 struct SRepositoryCompiled
258 SRepositoryBase* iHdr; // Always the first member!
259 SSettingC* iOrderedSettingList;
263 /** Byte type for large setting value data
265 typedef TUint8 TSettingData;
267 /** This class is the root object for a file or memory based settings
268 repository. It assumes the repository has a flat contiguous layout and
269 employees offsets to data rather then C++ pointers as in compiled
270 setting repositories.
271 All offsets are relative to the address of &iHdr member.
272 The last two members are expected to be present in the file/memory as shown
273 although there is no way at type definition time to know the size of these
274 members, hence they are commented out and will be accessed in the code
275 using memory/file address arithmetic.
277 struct SRepositoryFile
279 SRepositoryBase iHdr; // Always the first member!
280 TUint32 iLSDfirstByteOffset;
282 TUint32 iReserved[3];
283 // SSettingF iOrderedSettingList[iNumSettings];
284 // TSettingData iLargeSettingsData[iLSDataSize];
290 // -- GLOBALS -----------------------------------------------------------------
294 Global entry point used by PIL to create the variant HCR object in the PSL
297 @return Pointer to variant is successfully, 0 otherwise.
300 GLREF_C HCR::MVariant* CreateHCRVariant();
304 // -- MACROS ------------------------------------------------------------------
308 Global macro for use in defining the finger print field of a
309 SRepositoryCompiled.iHdr instance in the PSL compiled repository static data.
311 Macro used in PSL source as the value for the finger print field in a
313 @see SRepositoryBase::iFingerPrint
315 #define HCR_FINGER_PRINT {'H', 'C', 'R'}
318 Global macro for use in defining the finger print field of a
319 SRepositoryCompiled.iHdr instance in the PSL compiled repository static data.
321 Macro used in PSL source as the value for the finger print field in a
323 @see SRepositoryBase::iFingerPrint
325 #define HCR_SETTING_COUNT(a) (sizeof(a)/sizeof(SSettingC))
328 Global macro for use in setting the flags attribute of a SSettingC
329 instance in the PSL compiled repository static data.
332 @see HCR::SRepositoryCompiled
334 #define HCR_FLAGS_NONE HCR::EPropUndefined
337 Global macro for use in setting the length attribute of a SSettingC
338 instance in the PSL compiled repository static data.
341 @see HCR::SRepositoryCompiled
343 #define HCR_LEN_NA 0x0000
346 Global macro for use in defining the actual integer (word) value of a SettingC
347 instance in the PSL compiled repository static data. This can be used to
348 simplify the setting table for settings with the type flag
349 set to one of 0x0000FFFF.
352 @see HCR::SRepositoryCompiled
354 #define HCR_WVALUE(a) static_cast<TInt32>(a)
357 Global macro for use in assigning the address of a large setting value to an
358 instance of a SettingC in the PSL compiled repository static data. This can be
359 used to simplify the setting table for settings with the type flag
360 set to one of 0xFFFF0000.
363 @see HCR::SRepositoryCompiled
365 #define HCR_LVALUE(a) reinterpret_cast<TInt32>(a)
368 Global macro used as last entry in a PSL compiled repository static data.
369 The main use of this is to avoid the "last entry needs no following comma" issue
370 and to aid HCR initial thead testing.
371 The Setting (0xffffffff, 0xffffffff) was choosen as it should never appear in
372 a real variant as this category UID can not be allocated offically. Testers
373 should also be aware of the special use of this setting so as not to use it in
377 @see HCR::SRepositoryCompiled
379 #define HCR_LAST_SETTING { { { 0xFFFFFFFF, 0xFFFFFFFF}, ETypeUInt32, HCR_FLAGS_NONE, HCR_LEN_NA }, { { 0x4C415354 }}}