sl@0: // Copyright (c) 2008-2009 Nokia Corporation and/or its subsidiary(-ies). sl@0: // All rights reserved. sl@0: // This component and the accompanying materials are made available sl@0: // under the terms of the License "Eclipse Public License v1.0" sl@0: // which accompanies this distribution, and is available sl@0: // at the URL "http://www.eclipse.org/legal/epl-v10.html". sl@0: // sl@0: // Initial Contributors: sl@0: // Nokia Corporation - initial contribution. sl@0: // sl@0: // Contributors: sl@0: // sl@0: // Description: sl@0: // Hardware Configuration Respoitory Platform Independent Layer (PIL) sl@0: // sl@0: sl@0: sl@0: /** sl@0: @file hcr.h sl@0: Kernel side client API for Hardware Configuration Repository (HCR). sl@0: The HCR service provides access to hardware settings defined for the base port. sl@0: This API is used by kernel side components such as PDDs, hardware service sl@0: providers and other kernel extensions. sl@0: sl@0: @publishedPartner sl@0: @prototype sl@0: */ sl@0: sl@0: sl@0: sl@0: #ifndef HCR_H sl@0: #define HCR_H sl@0: sl@0: sl@0: // -- INCLUDES ---------------------------------------------------------------- sl@0: sl@0: sl@0: #include sl@0: #include sl@0: #include sl@0: #include sl@0: sl@0: sl@0: // -- CLASSES ----------------------------------------------------------------- sl@0: sl@0: /** sl@0: The HCR namespace contains all the types and APIs that make up the sl@0: client API of the Kernel Hardware Configuration Repository (HCR). sl@0: It provides accessor functions to retrieve settings held by the HCR and may be sl@0: called by kernel components from with in thread context. sl@0: sl@0: The _published_ Setting IDs available for use with this API can be found sl@0: in the BSP exported header 'hcrconfig.h'. This provides the top-level header sl@0: that clients can include to gain access to all IDs for the BSP. IDs for settings sl@0: that are internal to a component and not used by others are defined in a file sl@0: private to that component. sl@0: sl@0: The HCR supports a number of setting repositories and searches them in a defined sl@0: order, always returns the first setting found matching the ID or criteria. sl@0: This allows setting values to be overriden by more recent repositories created sl@0: during platform development and product creation. sl@0: */ sl@0: namespace HCR sl@0: { sl@0: sl@0: /** Maximum length of a large setting type, in bytes */ sl@0: static const TInt KMaxSettingLength = 512; sl@0: sl@0: sl@0: /** Setting category identifier type */ sl@0: typedef TUint32 TCategoryUid; sl@0: sl@0: /** Setting element identifier type */ sl@0: typedef TUint32 TElementId; sl@0: sl@0: /** The setting Identifier structure. Used to create static initialised sl@0: arrys for use with multiple setting retrieval calls. sl@0: */ sl@0: struct SSettingId sl@0: { sl@0: TCategoryUid iCat; //!< Allocated UID for setting category sl@0: TElementId iKey; //!< Element indetifier for setting in category sl@0: }; sl@0: sl@0: /** The setting Identifier type. A class used to uniquely identify a sl@0: setting in the HCR. Used in calls to HCR API to retrieve one setting. sl@0: */ sl@0: class TSettingId : public SSettingId sl@0: { sl@0: public: sl@0: TSettingId () sl@0: { iCat = iKey = 0; }; sl@0: TSettingId (TCategoryUid aCat, TElementId aKey) sl@0: { iCat = aCat; iKey = aKey; }; sl@0: TSettingId (const SSettingId& aId) sl@0: { iCat = aId.iCat; iKey = aId.iKey; }; sl@0: TSettingId& operator= (const SSettingId& rhs) sl@0: { iCat = rhs.iCat; iKey = rhs.iKey; return *this; } sl@0: sl@0: }; sl@0: sl@0: /** The setting types supported. The types are shown in two groups: Word sl@0: size - a maximum of 4 bytes; and ii) Large size - types exceeding 4 bytes sl@0: in size. sl@0: */ sl@0: enum TSettingType sl@0: { sl@0: ETypeUndefined = 0, //!< Type unknown/not set sl@0: sl@0: // Word size settings sl@0: ETypeInt32 = 0x00000001, //!< 32bit signed integer sl@0: ETypeInt16 = 0x00000002, //!< 16bit signed integer sl@0: ETypeInt8 = 0x00000004, //!< 8bit signed integer sl@0: ETypeBool = 0x00000008, //!< 32bit boolean value sl@0: ETypeUInt32 = 0x00000010, //!< 32bit unsigned integer sl@0: ETypeUInt16 = 0x00000020, //!< 16bit unsigned integer sl@0: ETypeUInt8 = 0x00000040, //!< 8bit unsigned integer sl@0: ETypeLinAddr = 0x00000100, //!< 32bit virtual address sl@0: sl@0: // Large settings sl@0: ETypeBinData = 0x00010000, //!< Raw binary data (TUint8 array) sl@0: ETypeText8 = 0x00020000, //!< String data (TText8 array) sl@0: ETypeArrayInt32 = 0x00040000, //!< 32bit signed integer array sl@0: ETypeArrayUInt32 = 0x00080000, //!< 32bit unsigned integer array sl@0: ETypeInt64 = 0x01000000, //!< 64bit signed integer sl@0: ETypeUInt64 = 0x02000000, //!< 64bit unsigned integer sl@0: }; sl@0: sl@0: sl@0: /** sl@0: Retrieve a word size integer setting value from the HCR. sl@0: On error aValue is undefined. sl@0: sl@0: @param aId in: The setting identifier sl@0: @param aValue out: The retrieved setting data value sl@0: sl@0: @return KErrNone if successful, output parameters valid sl@0: KErrNotFound if aId is not a known setting ID sl@0: KErrArgument if the setting identified is not the correct type sl@0: KErrNotReady if the HCR is used before it has been initialised sl@0: KErrCorrupt if HCR finds a repository to be corrupt sl@0: KErrGeneral if an internal failure occurs, see trace. sl@0: Otherwise one of the other system-wide error codes. sl@0: sl@0: @pre Call from thread context, during Init1 or later sl@0: */ sl@0: IMPORT_C TInt GetInt(const TSettingId& aId, TInt8& aValue); sl@0: IMPORT_C TInt GetInt(const TSettingId& aId, TInt16& aValue); sl@0: IMPORT_C TInt GetInt(const TSettingId& aId, TInt32& aValue); sl@0: IMPORT_C TInt GetInt(const TSettingId& aId, TInt64& aValue); sl@0: sl@0: /** sl@0: Retrieve a boolean setting value from the HCR. sl@0: On error aValue is undefined. sl@0: sl@0: @param aId in: The setting identifier sl@0: @param aValue out: The retrieved setting data value sl@0: sl@0: @return KErrNone if successful, output parameters valid sl@0: KErrNotFound if aId is not a known setting ID sl@0: KErrArgument if the setting identified is not the correct type sl@0: KErrNotReady if the HCR is used before it has been initialised sl@0: KErrCorrupt if HCR finds a repository to be corrupt sl@0: KErrGeneral if an internal failure occurs, see trace. sl@0: Otherwise one of the other system-wide error codes. sl@0: sl@0: @pre Call from thread context, during Init1 or later sl@0: */ sl@0: IMPORT_C TInt GetBool(const TSettingId& aId, TBool& aValue); sl@0: sl@0: /** sl@0: Retrieve an word size unsigned integer setting value from the HCR. sl@0: On error aValue is undefined. sl@0: sl@0: @param aId in: The setting identifier sl@0: @param aValue out: The retrieved setting data value sl@0: sl@0: @return KErrNone if successful, output parameters valid sl@0: KErrNotFound if aId is not a known setting ID sl@0: KErrArgument if the setting identified is not the correct type sl@0: KErrNotReady if the HCR is used before it has been initialised sl@0: KErrCorrupt if HCR finds a repository to be corrupt sl@0: KErrGeneral if an internal failure occurs, see trace. sl@0: Otherwise one of the other system-wide error codes. sl@0: sl@0: @pre Call from thread context, during Init1 or later sl@0: */ sl@0: IMPORT_C TInt GetUInt(const TSettingId& aId, TUint8& aValue); sl@0: IMPORT_C TInt GetUInt(const TSettingId& aId, TUint16& aValue); sl@0: IMPORT_C TInt GetUInt(const TSettingId& aId, TUint32& aValue); sl@0: IMPORT_C TInt GetUInt(const TSettingId& aId, TUint64& aValue); sl@0: sl@0: /** sl@0: Retrieve a word size linear address setting value from the HCR. sl@0: On error aValue is undefined. sl@0: sl@0: @param aId in: The setting identifier sl@0: @param aValue out: The retrieved setting data value sl@0: sl@0: @return KErrNone if successful, output parameters valid sl@0: KErrNotFound if aId is not a known setting ID sl@0: KErrArgument if the setting identified is not the correct type sl@0: KErrNotReady if the HCR is used before it has been initialised sl@0: KErrCorrupt if HCR finds a repository to be corrupt sl@0: KErrGeneral if an internal failure occurs, see trace. sl@0: Otherwise one of the other system-wide error codes. sl@0: sl@0: @pre Call from thread context, during Init1 or later sl@0: */ sl@0: IMPORT_C TInt GetLinAddr(const TSettingId& aId, TLinAddr& aValue); sl@0: sl@0: sl@0: /** sl@0: Retrieve a large binary data setting value from the HCR. The value sl@0: is copied into the supplied descriptor buffer. sl@0: On error the descriptor and output arguments have undefined values. sl@0: sl@0: @param aId in: The setting identifier sl@0: @param aValue inout: A pre-allocated descriptor to hold the value sl@0: sl@0: @return KErrNone if successful and aValue has been set sl@0: KErrNotFound if aId is not a known setting ID sl@0: KErrArgument if the setting identified is not the correct type sl@0: KErrNotReady if the HCR is used before it has been initialised sl@0: KErrCorrupt if HCR finds a repository to be corrupt sl@0: KErrTooBig if the setting is larger than the supplied buffer sl@0: KErrGeneral if an internal failure occurs, see trace sl@0: Otherwise one of the other system-wide error codes. sl@0: sl@0: @pre Call from thread context, during Init1 or later sl@0: */ sl@0: IMPORT_C TInt GetData(const TSettingId& aId, TDes8& aValue); sl@0: sl@0: /** sl@0: Retrieve a large binary data setting value from the HCR. The value is copied sl@0: into the supplied byte array buffer. sl@0: On error the buffer and output arguments have undefined values. sl@0: sl@0: @param aId in: The setting identifier sl@0: @param aMaxLen in: The maximum value length that can be stored in the buffer sl@0: @param aValue inout: The address of a pre-allocated buffer to hold the value sl@0: @param aLen out: Contains the length of the setting value written sl@0: sl@0: @return KErrNone if successful and aValue has been set sl@0: KErrNotFound if aId is not a known setting ID sl@0: KErrArgument if the setting identified is not the correct type sl@0: KErrNotReady if the HCR is used before it has been initialised sl@0: KErrCorrupt if HCR finds a repository to be corrupt sl@0: KErrTooBig if the setting is larger than the supplied buffer sl@0: KErrGeneral if an internal failure occurs, see trace sl@0: Otherwise one of the other system-wide error codes. sl@0: sl@0: @pre Call from thread context, during Init1 or later sl@0: */ sl@0: IMPORT_C TInt GetData(const TSettingId& aId, TUint16 aMaxLen, sl@0: TUint8* aValue, TUint16& aLen); sl@0: sl@0: /** sl@0: Retrieve an 8 bit character string setting from the HCR. The value sl@0: is copied into the supplied descriptor buffer. Note the string is not zero sl@0: terminated. sl@0: On error the descriptor and output arguments have undefined values. sl@0: sl@0: @param aId in: The setting identifier sl@0: @param aValue inout: A pre-allocated descriptor to hold the value sl@0: sl@0: @return KErrNone if successful and aValue has been set sl@0: KErrNotFound if aId is not a known setting ID sl@0: KErrArgument if the setting identified is not the correct type sl@0: KErrNotReady if the HCR is used before it has been initialised sl@0: KErrCorrupt if HCR finds a repository to be corrupt sl@0: KErrTooBig if the setting is larger than the supplied buffer sl@0: KErrGeneral if an internal failure occurs, see trace sl@0: Otherwise one of the other system-wide error codes. sl@0: sl@0: @pre Call from thread context, during Init1 or later sl@0: */ sl@0: IMPORT_C TInt GetString(const TSettingId& aId, TDes8& aValue); sl@0: sl@0: /** sl@0: Retrieve an 8 bit character string setting from the HCR. The value sl@0: is copied into the byte array buffer. Note the string is not zero sl@0: terminated. sl@0: On error the descriptor and output arguments have undefined values. sl@0: sl@0: @param aId in: The setting identifier sl@0: @param aMaxLen in: The maximum value length that can be stored in the buffer sl@0: @param aValue inout: The address of a pre-allocated buffer to hold the value sl@0: @param aLen out: Contains the length of the setting value written sl@0: sl@0: @return KErrNone if successful and aValue has been set sl@0: KErrNotFound if aId is not a known setting ID sl@0: KErrArgument if the setting identified is not the correct type sl@0: KErrNotReady if the HCR is used before it has been initialised sl@0: KErrCorrupt if HCR finds a repository to be corrupt sl@0: KErrTooBig if the setting is larger than the supplied buffer sl@0: KErrGeneral if an internal failure occurs, see trace sl@0: Otherwise one of the other system-wide error codes. sl@0: sl@0: @pre Call from thread context, during Init1 or later sl@0: */ sl@0: IMPORT_C TInt GetString(const TSettingId& aId, TUint16 aMaxLen, sl@0: TText8* aValue, TUint16& aLen); sl@0: sl@0: /** sl@0: Retrieve an array of signed integers from the HCR. The value sl@0: is copied into the byte array buffer. sl@0: On error the descriptor and output arguments have undefined values. sl@0: sl@0: @param aId in: The setting identifier sl@0: @param aMaxLen in: The maximum value length that can be stored in the buffer sl@0: @param aValue inout: The address of a pre-allocated word array to hold the value sl@0: @param aLen out: Contains the length, in bytes of the setting value written sl@0: sl@0: @return KErrNone if successful and aValue has been set sl@0: KErrNotFound if aId is not a known setting ID sl@0: KErrArgument if the setting identified is not the correct type sl@0: KErrNotReady if the HCR is used before it has been initialised sl@0: KErrCorrupt if HCR finds a repository to be corrupt sl@0: KErrTooBig if the setting is larger than the supplied buffer sl@0: KErrGeneral if an internal failure occurs, see trace sl@0: Otherwise one of the other system-wide error codes. sl@0: sl@0: @pre Call from thread context, during Init1 or later sl@0: */ sl@0: IMPORT_C TInt GetArray(const TSettingId& aId, TUint16 aMaxLen, sl@0: TInt32* aValue, TUint16& aLen); sl@0: IMPORT_C TInt GetArray(const TSettingId& aId, TUint16 aMaxLen, sl@0: TUint32* aValue, TUint16& aLen); sl@0: sl@0: /** sl@0: Retrieve multiple word sized settings from the Hardware Configuration sl@0: Repository in one call. This method can be used for all settings of size 4 sl@0: bytes or less (i.e those with a type less than 0x0000ffff). sl@0: The caller is responsible for pre-allocating the arrays supplied. Note the sl@0: array of setting IDs (aIds) supplied by the client must be ordered with sl@0: aIds[0] containing the lowest and aIds[aNum-1] the highest. Undefined sl@0: behaviour will result if this pre-condition is not met. sl@0: sl@0: On successful return the client will need to check the number found (return sl@0: value) matches their needs and cast each value in the aValues sl@0: array to the correct type before use. The correct type is either known at sl@0: compile time by the caller or determined from aTypes, if supplied. sl@0: sl@0: When an overall error is returned from the function the output arrays have sl@0: undefined values. sl@0: sl@0: @param aNum in: The number of settings to retrieve. It is also the sl@0: size of the arrays in the following arguments sl@0: @param aIds in: An ordered array of setting identifiers to retrieve sl@0: @param aValues inout: An array of values, populated on exit sl@0: @param aTypes inout: An optional array of type enumerations, populated on sl@0: exit describing the type of each setting found. sl@0: May be 0 if client is not interested sl@0: @param aErrors inout: An array of search errors for each setting populated sl@0: on exit. If no error found for the setting then KErrNone sl@0: is written. Possible error codes: sl@0: KErrArgument the setting is not of a suitable type sl@0: KErrNotFound the setting is not found sl@0: KErrNone when setting found sl@0: sl@0: sl@0: @return Zero or positive number of settings found, -ve on error sl@0: KErrArgument if some parameters are wrong(i.e. aErrors is a null sl@0: pointer, aNum is negative and so on) sl@0: KErrCorrupt if HCR finds a repository to be corrupt sl@0: KErrGeneral if an internal failure occurs, see trace sl@0: KErrNotReady if the HCR is used before it has been initialised sl@0: KErrNoMemory if the memory allocation within this function failed sl@0: Otherwise one of the other system-wide error codes. sl@0: sl@0: @pre Call from thread context, during Init1 or later sl@0: */ sl@0: IMPORT_C TInt GetWordSettings(TInt aNum, const SSettingId aIds[], sl@0: TInt32 aValues[], TSettingType aTypes[], TInt aErrors[]); sl@0: sl@0: sl@0: /** sl@0: Retrieve the type and size of a HCR setting. Can be used by clients to sl@0: obtain the setting size should a buffer need to be allocated. sl@0: On error the output arguments are undefined. sl@0: sl@0: @param aId in: The setting identifier sl@0: @param aType out: The type enumeration of the found setting sl@0: @param aLen out: The length in bytes of the found setting sl@0: sl@0: @return KErrNone if successful, output parameters valid sl@0: KErrNotFound if aId is not a known setting ID sl@0: KErrNotReady if the HCR is used before it has been initialised sl@0: KErrCorrupt if HCR finds a repository to be corrupt sl@0: KErrGeneral if an internal failure occurs, see trace sl@0: Otherwise one of the other system-wide error codes. sl@0: sl@0: @pre Call from thread context, during Init1 or later sl@0: */ sl@0: IMPORT_C TInt GetTypeAndSize(const TSettingId& aId, sl@0: TSettingType& aType, TUint16& aLen); sl@0: sl@0: /** sl@0: Retrieve the number of unique ettings held in the HCR for one particular sl@0: category. It allows a client to perpare buffers for other calls to the HCR sl@0: to retrieve these settings. sl@0: The method carries out a search to return the total number of unique setting sl@0: records found across all HCR repositories for a given category. It does not sl@0: count settings that are duplicate from being redefined in different sl@0: repositories. sl@0: The function is particularly useful for open-ended categories were the sl@0: run-time client can not predict the number of settings prvisioned. sl@0: sl@0: @param aCatUid in: The setting identifier category to use in the search sl@0: sl@0: @return Zero or positive number of settings found in category, -ve on error sl@0: KErrNotReady if the HCR is used before it has been initialised sl@0: KErrCorrupt if HCR finds a repository to be corrupt sl@0: KErrGeneral if an internal failure occurs, see trace sl@0: Otherwise one of the other system-wide error codes. sl@0: sl@0: @pre Call from thread context, during Init1 or later sl@0: */ sl@0: IMPORT_C TInt FindNumSettingsInCategory (TCategoryUid aCatUid); sl@0: sl@0: /** sl@0: Retrieve details of all the settings (ids, types and sizes) in one sl@0: particular category. This function can be used by clients to obtain the sl@0: number of, ids, sizes and types of all the settings in a category. sl@0: It allows a client to alloc buffers for other calls to the HCR to retrieve sl@0: the values of these settings. sl@0: sl@0: On successful return the client will need to check the number found (return sl@0: value) matches the expected number. When there are more defined in sl@0: the category than was able to be returned, i.e. when number found sl@0: exceeded aMaxNum then aMaxNum is returned. sl@0: sl@0: When an overall error is returned from the function the output arrays have sl@0: undefined values. sl@0: sl@0: @param aCat in: The setting category to search for sl@0: @param aMaxNum in: The maximum number of settings to return. It is also sl@0: the size of the arrays in the following arguments sl@0: @param aKeyIds inout: Client supplied array populated on exit. Large sl@0: enough to hold all elements in category. sl@0: @param aTypes inout: Client supplied array populated with setting types sl@0: enumerations on exit. Array address may be 0 if sl@0: client is not interested. sl@0: @param aLens inout: Client supplied array populated with setting lengths sl@0: on exit for those settings with a type > 0x0000ffff. sl@0: When less than this 0 is set in the aLens array element. sl@0: Array address may be 0 if client is not interested. sl@0: sl@0: @return Zero or positive number of settings found in category, -ve on error sl@0: KErrArgument if some parameters are wrong(i.e. aErrors is a null sl@0: pointer, aNum is negative and so on) sl@0: KErrNotReady if the HCR is used before it has been initialised sl@0: KErrCorrupt if HCR finds a repository to be corrupt sl@0: KErrGeneral if an internal failure occurs, see trace sl@0: Otherwise one of the other system-wide error codes. sl@0: sl@0: @pre Call from thread context, during Init1 or later sl@0: */ sl@0: IMPORT_C TInt FindSettings(TCategoryUid aCatUid, TInt aMaxNum, sl@0: TElementId aKeyIds[], TSettingType aTypes[], TUint16 aLens[]); sl@0: sl@0: /** sl@0: Retrieve details of all the settings (ids, types and sizes) in one sl@0: particular category who's key ID matches the supplied bit pattern/mask. sl@0: This function can be used by clients to obtain the number of, ids, sizes sl@0: and types of all the settings in a category. It allows a client to alloc sl@0: buffers for other calls to the HCR to retrieve the values of these settings. sl@0: sl@0: This search method allows categories to contain structured settings sl@0: i.e. row/column structured or record based categories as might be used sl@0: for configuration data of a hardware service provider. sl@0: sl@0: The caller supplies the category to search, a setting key ID mask and the sl@0: pattern to match. Setting keys that satisfy this logic are returned: sl@0: ((elementID & aElementMask) == (aPattern & aElementMask)) sl@0: sl@0: For example, a set of driver capability structures might be encoded into sl@0: an element ID where the 24 MSb are the row/record number and the 8 LSb sl@0: are the column/field index. Thus to retrieve all fields in row 2 supply: sl@0: aElemMask = 0xffffff00, aPattern = 0x000002** sl@0: to retrieve key fields of all records supply: sl@0: aElemMask = 0x000000ff, aPattern = 0x******01 sl@0: (* = dont care) sl@0: sl@0: On successful return the client will need to check the number found (return sl@0: value) matches the expected number. When there are more defined in sl@0: the category than was able to be returned, i.e. when number found sl@0: exceeded aMaxNum then aMaxNum is returned. sl@0: sl@0: When an overall error is returned from the function the output arrays have sl@0: undefined values. sl@0: sl@0: @param aCat in: The category to retrieve settings for sl@0: @param aMaxNum in: The maximum number of settings to retrieve. It is also sl@0: the size of the arrays in the following arguments sl@0: @param aMask in: The bits in the Element ID to be checked against sl@0: aPattern sl@0: @param aPattern in: Identified the bits that must be set for a sl@0: setting to be returned in the search sl@0: @param aKeyIds inout: Client supplied array populated on exit. Large sl@0: enough to hold aMaxNum element ids. sl@0: @param aTypes inout: Client supplied array populated with setting types sl@0: enumerations on exit. Array address may be 0 if sl@0: client is not interested. sl@0: @param aLens inout: Client supplied array populated with setting lengths sl@0: on exit for those settings with a type > 0x0000ffff. sl@0: When less than this 0 is set in the aLens array element. sl@0: Array address may be 0 if client is not interested. sl@0: sl@0: @return Zero or positive number of settings found in category, -ve on error sl@0: KErrArgument if some parameters are wrong(i.e. aErrors is a null sl@0: pointer, aNum is negative and so on) sl@0: KErrNotReady if the HCR is used before it has been initialised sl@0: KErrCorrupt if HCR finds a repository to be corrupt sl@0: KErrGeneral if an internal failure occurs, see trace sl@0: KErrNoMemory if the memory allocation within this function failed sl@0: Otherwise one of the other system-wide error codes. sl@0: sl@0: sl@0: @pre Call from thread context, during Init1 or later sl@0: */ sl@0: IMPORT_C TInt FindSettings(TCategoryUid aCat, TInt aMaxNum, sl@0: TUint32 aMask, TUint32 aPattern, TElementId aKeyIds[], sl@0: TSettingType aTypes[], TUint16 aLens[]); sl@0: sl@0: } sl@0: sl@0: #endif // HCR_H sl@0: