os/kernelhwsrv/kernel/eka/drivers/hcr/hcr_hai.h
author sl
Tue, 10 Jun 2014 14:32:02 +0200
changeset 1 260cb5ec6c19
permissions -rw-r--r--
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".
     7 //
     8 // Initial Contributors:
     9 // Nokia Corporation - initial contribution.
    10 //
    11 // Contributors:
    12 //
    13 // Description:
    14 // Hardware Configuration Respoitory Platform Independent Layer (PIL)
    15 // Contains the hardware abstraction interface implemented in the variant PSL
    16 // HCR kernel extension project.
    17 //
    18 
    19 /** 
    20 @file hcr_hai.h
    21 Kernel side definitions for the HCR Symbian Hardware Abstraction 
    22 Interface (SHAI) for variants to implement when creating a HCR.dll binary.
    23 
    24 @publishedPartner
    25 @prototype
    26 */
    27 
    28 #ifndef HCR_HAI_H
    29 #define HCR_HAI_H
    30 
    31 
    32 // -- INCLUDES ----------------------------------------------------------------
    33 
    34 
    35 #include <e32def.h>
    36 #include <e32err.h> 
    37 
    38 #include <drivers/hcr.h>
    39 
    40 
    41 // -- CLASSES -----------------------------------------------------------------
    42 
    43 
    44 /**
    45 The HCR namespace contains all the types and classes that make up the
    46 Kernel side Hardware Configuration Repository (HCR).
    47 */
    48 namespace HCR
    49     {
    50 	/** Constant defined for the first HCR repository format. Used for both 
    51 	compiled and file repositories. 	
    52 	@see SRepositoryBase::iFormatVersion	
    53 	*/	    
    54     static const TInt KRepositoryFirstVersion = 0x0001;
    55     
    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.       
    61     */
    62     class MVariant
    63         {
    64     public:
    65     
    66         /** 
    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.
    70 
    71     	@return	KErrNone if successful, or any other system wide error code.
    72         */    
    73         virtual TInt Initialise() = 0;
    74         
    75         
    76     	/**
    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. 
    80          
    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
    86        	*/
    87         virtual TInt GetCompiledRepositoryAddress(TAny* & aAddr) = 0;
    88         
    89    	    /**
    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 
    93 		this repository. 	
    94          
    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
    97        	*/
    98         virtual TBool IgnoreCoreImgRepository () = 0;
    99         
   100     	/**
   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.
   106          
   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
   112        	*/
   113         virtual TInt GetOverrideRepositoryAddress(TAny* & aAddr) = 0;
   114         
   115         };       
   116         
   117         
   118     /** Union that holds one of the supported word-sized setting values 
   119     */
   120     union UValueWord
   121         {
   122         TInt32      iInt32;
   123         TInt16      iInt16;
   124         TInt8       iInt8;
   125         TBool       iBool;
   126         TUint32     iUInt32;
   127         TUint16     iUInt16;
   128         TUint8      iUInt8;
   129         TLinAddr    iAddress;
   130         };
   131 
   132     /** Union that holds a pointer to one of the supported large value types 
   133     */
   134     union UValueLarge
   135         {
   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
   142         };
   143     
   144     /** Type used to hold the offset to a large setting value */
   145     typedef TInt TValueLargeOffset;
   146       
   147     /** Union type used to hold either the literal value or a C++ pointer to 
   148     the value. Used in compile time settings.   
   149     */
   150     union USettingValueC
   151         {
   152         UValueWord  iLit;
   153         UValueLarge iPtr;
   154         };
   155 
   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
   158     mapped settings.   
   159     */
   160     union USettingValueF
   161         {
   162         UValueWord          iLit;
   163         TValueLargeOffset   iOffset;
   164         };
   165            
   166     /** Metadata flags to describe properties of the settings.
   167     */
   168     enum TSettingProperties
   169         {
   170         EPropUndefined     = 0x0000,   //!< Unknown/not set
   171    
   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
   176         
   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 
   183         };        
   184         
   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.    
   188     */
   189     struct SSettingBase
   190         {
   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
   195         };
   196             
   197     /** This structure holds a setting defined at compile time within a compile
   198     time defined repository.     
   199     @see SRepositoryCompiled
   200     */
   201     struct SSettingC            // : public SSettingBase
   202         {
   203         SSettingBase    iName;  // Always the first member!
   204         USettingValueC  iValue;
   205         };
   206 
   207     /** This structure holds a setting define in a file or memory within a file
   208     based repository.     
   209     @see SRepositoryFile
   210     */
   211     struct SSettingF             // : public SSettingBase
   212         {
   213         SSettingBase    iName;   // Always the first member!
   214         USettingValueF  iValue;
   215         };
   216 
   217 
   218     /** Metadata flags to describe the repository type/layout.
   219     */
   220     enum TRepositoryType
   221         {
   222         EReposUndefined = 0x00,   //!< Unknown
   223         
   224         EReposCompiled  = 'c',   //!< Repository is in Compiled layout
   225         EReposFile      = 'f'    //!< Repository is in File layout
   226         };        
   227 
   228     /** Metadata flags to describe repository properties.
   229     */
   230     enum TRepositoryProperties
   231         {
   232         EReposClear       = 0x0000,   //!< Unknown
   233         EReposReadOnly    = 0x0001,   //!< Repository is read-only
   234         EReposNonVolatile = 0x0002    //!< Repository is writable, saved to flash
   235         };        
   236 
   237     /** Provides base class for setting repositories. All repository structures 
   238     start with this structure providing common repository attributes such as the
   239     type , size etc.   
   240     */
   241     struct SRepositoryBase
   242         {
   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
   248         };    
   249  
   250  
   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.
   255     */
   256     struct SRepositoryCompiled
   257         {
   258         SRepositoryBase*    iHdr;        // Always the first member!
   259         SSettingC*          iOrderedSettingList;
   260         };    
   261  
   262  
   263     /** Byte type for large setting value data 
   264     */
   265     typedef TUint8 TSettingData;
   266  
   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.
   276     */
   277     struct SRepositoryFile 
   278         {
   279         SRepositoryBase     iHdr;        // Always the first member!
   280         TUint32             iLSDfirstByteOffset;
   281 		TUint32             iLSDataSize;
   282 		TUint32				iReserved[3];
   283      // SSettingF           iOrderedSettingList[iNumSettings];
   284      // TSettingData        iLargeSettingsData[iLSDataSize];
   285         };    
   286   
   287     }
   288 
   289 
   290 // -- GLOBALS -----------------------------------------------------------------
   291 
   292 
   293 /**
   294 Global entry point used by PIL to create the variant HCR object in the PSL
   295 code.
   296 
   297 @return Pointer to variant is successfully, 0 otherwise.
   298 @see HCR::MVariant
   299 */
   300 GLREF_C HCR::MVariant* CreateHCRVariant(); 
   301 
   302 
   303 
   304 // -- MACROS ------------------------------------------------------------------
   305 
   306 
   307 /** 
   308 Global macro for use in defining the finger print field of a 
   309 SRepositoryCompiled.iHdr instance in the PSL compiled repository static data.
   310 
   311 Macro used in PSL source as the value for the finger print field in a
   312 compiled repository.
   313 @see SRepositoryBase::iFingerPrint
   314 */
   315 #define HCR_FINGER_PRINT {'H', 'C', 'R'}
   316 
   317 /** 
   318 Global macro for use in defining the finger print field of a 
   319 SRepositoryCompiled.iHdr instance in the PSL compiled repository static data.
   320 
   321 Macro used in PSL source as the value for the finger print field in a
   322 compiled repository.
   323 @see SRepositoryBase::iFingerPrint
   324 */
   325 #define HCR_SETTING_COUNT(a) (sizeof(a)/sizeof(SSettingC))
   326 
   327 /**
   328 Global macro for use in setting the flags attribute of a SSettingC 
   329 instance in the PSL compiled repository static data.
   330 
   331 @see HCR::MVariant
   332 @see HCR::SRepositoryCompiled
   333 */
   334 #define HCR_FLAGS_NONE		HCR::EPropUndefined
   335 
   336 /**
   337 Global macro for use in setting the length attribute of a SSettingC 
   338 instance in the PSL compiled repository static data.
   339 
   340 @see HCR::MVariant
   341 @see HCR::SRepositoryCompiled
   342 */
   343 #define HCR_LEN_NA			0x0000
   344 
   345 /**
   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.
   350 
   351 @see HCR::MVariant
   352 @see HCR::SRepositoryCompiled
   353 */
   354 #define HCR_WVALUE(a)	static_cast<TInt32>(a)
   355 
   356 /**
   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.
   361 
   362 @see HCR::MVariant
   363 @see HCR::SRepositoryCompiled
   364 */
   365 #define HCR_LVALUE(a)	reinterpret_cast<TInt32>(a)
   366 
   367 /**
   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
   374 a file repository.
   375 
   376 @see HCR::MVariant
   377 @see HCR::SRepositoryCompiled
   378 */
   379 #define HCR_LAST_SETTING { { { 0xFFFFFFFF, 0xFFFFFFFF}, ETypeUInt32, HCR_FLAGS_NONE, HCR_LEN_NA }, { { 0x4C415354 }}}
   380 
   381 
   382 #endif // HCR_HAI_H