kernel/eka/include/drivers/hcr.h
changeset 0 a41df078684a
child 31 56f325a607ea
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/kernel/eka/include/drivers/hcr.h	Mon Oct 19 15:55:17 2009 +0100
@@ -0,0 +1,396 @@
+// 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.h
+Kernel side API for Hardware Configuration Repository (HCR).
+
+
+===============================================================
+ ____            _        _                    
+|  _ \ _ __ ___ | |_ ___ | |_ _   _ _ __   ___ 
+| |_) | '__/ _ \| __/ _ \| __| | | | '_ \ / _ \
+|  __/| | | (_) | || (_) | |_| |_| | |_) |  __/
+|_|   |_|  \___/ \__\___/ \__|\__, | .__/ \___|
+                              |___/|_|         
+
+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_H
+#define HCR_H
+
+
+// -- INCLUDES ----------------------------------------------------------------
+
+
+#include <e32err.h>
+#include <e32def.h> 
+#include <e32cmn.h> 
+#include <e32des8.h>
+
+
+// -- CLASSES -----------------------------------------------------------------
+
+/**
+The HCR namespace contains all the types and APIs that make up the
+Kernel side Hardware Configuration Repository (HCR).
+It provides accessor functions to settings held by the HCR and may be used by 
+kernel side clients such as physical device drivers and other services from
+thread contexts.
+The published Setting IDs available for use with this API can be found
+in the BSP exported header 'hcrconfig.h'. This provides the top-level header
+that clients can include to gain access to all IDs for the BSP.
+*/
+namespace HCR
+    {
+
+    /** Maximum length of a large setting type, in bytes */     
+    static const TInt KMaxSettingLength = 512;
+
+
+    /** Setting category identifier type */
+    typedef TUint32 TCategoryUid;
+    
+    /** Setting element identifier type */
+    typedef TUint32 TElementId;
+        
+    /** The setting Identifier structure. Used to create static initialised
+    arrys for use with multiple setting retrieval calls.	
+	*/    
+    struct SSettingId
+	    {
+        TCategoryUid iCat;		//!< Allocated UID for setting category
+        TElementId iKey;		//!< Element indetifier for setting in category
+		};
+		
+    /** The setting Identifier type. A class used to uniquely identify a 
+    setting in the HCR. Used in calls to HCR API. 
+	*/
+    class TSettingId
+    	{
+    public:
+    	TSettingId ()
+		 { iCat = iKey = 0; };
+    	TSettingId (TCategoryUid aCat, TElementId aKey)
+    	 { iCat = aCat; iKey = aKey; };
+    	TSettingId (const SSettingId& aId)
+    	 { iCat = aId.iCat; iKey = aId.iKey; };
+		TSettingId& operator= (const SSettingId& rhs)
+		 { iCat = rhs.iCat; iKey = rhs.iKey; return *this; }  
+		   
+        /** The allocated UID identifying the category the setting belongs too */
+        TCategoryUid iCat;
+        
+        /** The integer key identifying the setting element in the category */
+        TElementId iKey;
+    	};
+    
+    /** The setting types supported. The types are shown in two groups: Word 
+    size - a maximum of 4 bytes; and ii) Large size - types exceeding 4 bytes 
+    in size.
+	*/
+    enum TSettingType
+    	{
+        ETypeUndefined  = 0,            //!< Type unknown/not set
+        
+        // Word size settings
+        ETypeInt32      = 0x00000001,   //!< 32bit signed integer
+        ETypeInt16      = 0x00000002,   //!< 16bit signed integer
+        ETypeInt8       = 0x00000004,   //!< 8bit signed integer
+        ETypeBool       = 0x00000008,   //!< 32bit boolean value
+        ETypeUInt32     = 0x00000010,   //!< 32bit unsigned integer
+        ETypeUInt16     = 0x00000020,   //!< 16bit unsigned integer
+        ETypeUInt8      = 0x00000040,   //!< 8bit unsigned integer
+        ETypeLinAddr    = 0x00000100,   //!< 32bit virtual address
+        
+        // Large settings
+        ETypeBinData   		= 0x00010000,   //!< Raw binary data (TUint8 array)
+        ETypeText8     		= 0x00020000,   //!< String data (TText8 array) 
+		ETypeArrayInt32 	= 0x00040000,	//!< 32bit signed integer array   
+		ETypeArrayUInt32	= 0x00080000,	//!< 32bit unsigned integer array
+        ETypeInt64     		= 0x01000000,   //!< 64bit signed integer
+        ETypeUInt64    		= 0x02000000,   //!< 64bit unsigned integer    
+     	};
+
+
+	/**
+    Retrieve settings of built in types from the HCR.
+    
+    @param aId     The setting identifier
+    @param aValue  The retrieved setting data value  
+    
+	@return	KErrNone if successful, output parameters valid
+            KErrNotFound if aId is not a known setting ID
+            KErrArgument if the setting identified is not the correct type
+            KErrNotReady if the HCR is used before it has been initialised
+            KErrCorrupt if HCR finds a repository to be corrupt
+            KErrGeneral if an internal failure occurs, see trace.
+
+	@pre    Call from thread context, during Init1 or later
+	*/
+	IMPORT_C TInt GetInt(const TSettingId& aId, TInt8& aValue);
+	IMPORT_C TInt GetInt(const TSettingId& aId, TInt16& aValue);
+	IMPORT_C TInt GetInt(const TSettingId& aId, TInt32& aValue);
+    IMPORT_C TInt GetInt(const TSettingId& aId, TInt64& aValue);
+	
+	IMPORT_C TInt GetBool(const TSettingId& aId, TBool& aValue);
+	
+	IMPORT_C TInt GetUInt(const TSettingId& aId, TUint8& aValue);
+    IMPORT_C TInt GetUInt(const TSettingId& aId, TUint16& aValue);
+    IMPORT_C TInt GetUInt(const TSettingId& aId, TUint32& aValue);
+    IMPORT_C TInt GetUInt(const TSettingId& aId, TUint64& aValue);
+
+    IMPORT_C TInt GetLinAddr(const TSettingId& aId, TLinAddr& aValue);
+    
+	/**
+    Retrieve a binary data (ETypeBinData) setting from the HCR.
+
+    @param aId     The setting identifier
+    @param aMaxLen The maximum value length that can be stored in the buffer
+    @param aValue  A pointer to the buffer or a descriptor to hold the value
+    @param aLen    Contains the length of the setting value written
+
+    
+	@return	KErrNone if successful and aValue has been set
+            KErrNotFound if aId is not a known setting ID
+            KErrArgument if the setting identified is not the correct type
+            KErrNotReady if the HCR is used before it has been initialised
+            KErrCorrupt if HCR finds a repository to be corrupt
+            KErrTooBig if the setting is larger than the supplied buffer
+            KErrGeneral if an internal failure occurs, see trace
+
+	@pre    Call from thread context, during Init1 or later
+	*/
+    IMPORT_C TInt GetData(const TSettingId& aId, TDes8& aValue);
+    IMPORT_C TInt GetData(const TSettingId& aId, TUint16 aMaxLen, 
+                                    TUint8* aValue, TUint16& aLen);        
+	/**
+    Retrieve a character string (ETypeText8) setting from the HCR.
+    
+    @param aId     The setting identifier
+    @param aMaxLen The maximum value length that can be stored in the buffer
+    @param aValue  A pointer to the buffer or a descriptor to hold the value
+	@param aLen    Contains the length of the setting value written    
+
+	@return	KErrNone if successful and aValue has been set
+            KErrNotFound if aId is not a known setting ID
+            KErrArgument if the setting identified is not the correct type
+            KErrNotReady if the HCR is used before it has been initialised
+            KErrCorrupt if HCR finds a repository to be corrupt
+            KErrTooBig if the setting is larger than the supplied buffer
+            KErrGeneral if an internal failure occurs, see trace
+
+	@pre    Call from thread context, during Init1 or later
+	*/
+    IMPORT_C TInt GetString(const TSettingId& aId, TDes8& aValue);
+    IMPORT_C TInt GetString(const TSettingId& aId, TUint16 aMaxLen, 
+                                    TText8* aValue, TUint16& aLen);
+                                                                        
+	/**
+    Retrieve an array setting from the HCR. All value length paramters are 
+	measured in bytes.
+
+    @param aId     The setting identifier
+    @param aMaxLen The maximum value length that can be stored in the buffer
+    @param aValue  A pointer to the buffer to hold the value
+    @param aLen    Contains the length of the setting value written
+    
+	@return	KErrNone if successful and aValue has been set
+            KErrNotFound if aId is not a known setting ID
+            KErrArgument if the setting identified is not the correct type
+            KErrNotReady if the HCR is used before it has been initialised
+            KErrCorrupt if HCR finds a repository to be corrupt
+            KErrTooBig if the setting is larger than the supplied buffer
+            KErrGeneral if an internal failure occurs, see trace
+
+	@pre    Call from thread context, during Init1 or later
+	*/
+    IMPORT_C TInt GetArray(const TSettingId& aId, TUint16 aMaxLen, 
+                                    TInt32* aValue, TUint16& aLen);        
+    IMPORT_C TInt GetArray(const TSettingId& aId, TUint16 aMaxLen, 
+                                    TUint32* aValue, TUint16& aLen);   
+									     
+    /**
+    Retrieve multiple simple settings from the Hardware Configuration 
+    Repository in one call. This method can be used for all settings of size 4 
+    byes or less (i.e those with a type in 0x0000ffff).
+    
+    @param aNum     in: The number of settings to retrieve. It is also the 
+                    size of the arrays in the following arguments
+    @param aIds     in:  An ordered array of setting identifiers to retrieve, lowest first
+    @param aValues  out: An array of values, populated on exit
+    @param aTypes   out: An optional array of type enumerations describing 
+                    the type of each setting found. May be 0 if client is 
+                    not interested
+    @param aErrors  out: An optional array of return codes to describe the 
+                    result of the lookup for each setting. May be 0 if 
+                    client is not interested
+    
+	@return	KErrNone if successful and all values have been retrieved
+			KErrArgument if one of the arguments is incorrect.
+            KErrNotFound if one or more setting IDs is not known 
+            KErrNotReady if the HCR is used before it has been initialised
+            KErrCorrupt if HCR finds a repository to be corrupt
+            KErrGeneral if an internal failure occurs, see trace
+            KErrNotSupported if method is not supported
+                
+	@pre    Call from thread context, during Init1 or later
+	*/    
+    IMPORT_C TInt GetWordSettings(TInt aNum, const SSettingId aIds[], 
+            TInt32 aValues[], TSettingType aTypes[], 
+                                     TInt aErrors[]);
+
+    /**
+    Retrieve the type and size of a HCR setting. Can be used by clients to 
+    obtain the setting size if a dynamic buffer is to be used.
+    
+    @param aId     The setting identifier
+    @param aType   The type enumeration of found setting
+    @param aLen    The length in bytes of found setting
+        
+	@return	KErrNone if successful, output parameters valid
+            KErrNotFound if aId is not a known setting ID
+            KErrNotReady if the HCR is used before it has been initialised
+            KErrCorrupt if HCR finds a repository to be corrupt
+            KErrGeneral if an internal failure occurs, see trace
+            KErrNotSupported if method is not supported
+
+	@pre    Call from thread context, during Init1 or later
+    */    
+    IMPORT_C TInt GetTypeAndSize(const TSettingId& aId, 
+                                        TSettingType& aType, TUint16& aLen);
+                                        
+    /**
+    Retrieve the number of settings held in the HCR for one particular category.
+	It allows a client to perpare buffers for other calls to the HCR to 
+	retrieve these settings.
+	This search method will return the total number of setting records found 
+	across all HCR repositories for a given category. It does not apply the 
+	override rules of other routines meaning that it counts duplicates to
+	maintain performance.
+    
+    @param aCatUid	in: The setting identifier category to use in the search
+        
+	@return	Zero or positive number of settings found in category, -ve on error
+            KErrNotReady if the HCR is used before it has been initialised
+            KErrCorrupt if HCR finds a repository to be corrupt
+            KErrGeneral if an internal failure occurs, see trace
+            KErrNotSupported if method is not supported
+
+	@pre    Call from thread context, during Init1 or later
+    */ 
+	IMPORT_C TInt FindNumSettingsInCategory (TCategoryUid aCatUid);
+	 
+    /**
+    Retrieve all the setting ids, types and sizes in one particular
+	category. Can be used by clients to obtain the number, size and types of 
+	all the settings in a category. It allows a client to alloc buffers for 
+	other calls to the HCR to retrieve these settings.
+    
+    @param aCatUid	 in: The setting identifier category to use in the search
+    @param aMaxNum   in: The maximum number of settings to return. It is also 
+                         the size of the arrays in the following arguments   
+    
+    @param aNumFound out: The number of settings found 
+    @param aElIds    inout: Client supplied array populated on exit. Large
+						    enough to hold all elements in category.
+    @param aTypes	 inout: Client supplied array populated with setting types 
+						    enumerations on exit. May be 0 if client is 
+                            not interested.
+    @param aLen  	 inout: Client supplied array populated with setting lengths
+						    on exit. May be 0 if client is not interested.
+        
+	@return	Zero or positive number of settings found in category, -ve on error
+            KErrOverflow if ok but with more settings than aMaxNum were found
+			KErrNotReady if the HCR is used before it has been initialised
+            KErrCorrupt if HCR finds a repository to be corrupt
+            KErrGeneral if an internal failure occurs, see trace
+            KErrNotSupported if method is not supported
+
+	@pre    Call from thread context, during Init1 or later
+    */ 
+    IMPORT_C TInt FindSettings(TCategoryUid aCatUid, 
+					TInt aMaxNum, TUint32& aNumFound, 
+					TElementId* aElIds, TSettingType* aTypes, TUint16* aLens);
+                                       
+    /** 
+    Finds multiple settings in the Hardware Configuration Repository who's
+    setting ID matches the supplied search bit pattern. This method is useful 
+    for categories that contain structured settings i.e. row/column structured 
+    or record based categories as might be the case with hardware service
+    providers.
+    
+    The caller supplies the category to search, an element ID mask and the 
+    pattern to match. SettingIDs that satisfy this logic are returned:
+    ((elementID & aElementMask) == (aPattern & aElementMask))
+    
+    For example, a set of driver capability structures might be encoded into
+    an element ID where the 24 MSb are the row/record number and the 8 LSb 
+    are the column/field index. Thus to retrieve all fields in row 2 supply: 
+        aElemMask = 0xffffff00, aPattern = 0x000002** 
+    to retrieve key fields of all records supply:
+        aElemMask = 0x000000ff, aPattern = 0x******01
+    (* = dont care)
+   
+    @param aCat      in: The category to retrieve settings for
+    @param aMaxNum   in: The maximum number of settings to retrieve. It is also 
+                         the size of the arrays in the following arguments   
+    @param aAtId     in: The Minimum element ID to commence the search at. 
+                         Used when retrieving settings in batches.
+    @param aElemMask in: Element ID mask.
+    @param aPattern  in: Identifies the set of fieldy to return in the search.
+						                   
+    @param aNumFound out: The number of settings found 
+    @param aElIds    inout: Client supplied array populated on exit. Large
+						    enough to hold aMaxNum element ids.
+    @param aTypes    inout: Client supplied array populated with setting types 
+						    enumerations on exit. May be 0 if client is 
+                            not interested.
+    @param aLen  	 inout: Client supplied array populated with setting lengths
+						    on exit. May be 0 if client is not interested.
+    
+	@return	Zero or positive number of settings found in category, -ve on error
+            KErrOverflow if ok but with more settings than aMaxNum were found 
+            KErrNotReady if the HCR is used before it has been initialised
+            KErrCorrupt if HCR finds a repository to be corrupt
+            KErrGeneral if an internal failure occurs, see trace
+            KErrNotSupported if method is not supported
+         
+	@pre    Call from thread context, during Init1 or later
+	*/    
+    IMPORT_C TInt FindSettings(TCategoryUid aCat, 
+					TInt aMaxNum, TUint32 aAtId,
+                    TUint32 aMask, TUint32 aPattern, TUint32& aNumFound,
+                    TElementId* aElIds, TSettingType* aTypes, TUint16* aLens);
+     
+}
+
+#endif // HCR_H
+