diff -r 538db54a451d -r 5d2844f35677 kernel/eka/include/drivers/hcr.h --- a/kernel/eka/include/drivers/hcr.h Mon Jan 18 21:31:10 2010 +0200 +++ b/kernel/eka/include/drivers/hcr.h Tue Jan 26 13:13:38 2010 +0200 @@ -17,8 +17,10 @@ /** @file hcr.h -Kernel side API for Hardware Configuration Repository (HCR). The HCR service -provides access to hardware settings defined for the base port. +Kernel side client API for Hardware Configuration Repository (HCR). +The HCR service provides access to hardware settings defined for the base port. +This API is used by kernel side components such as PDDs, hardware service +providers and other kernel extensions. @publishedPartner @prototype @@ -26,7 +28,6 @@ - #ifndef HCR_H #define HCR_H @@ -44,13 +45,20 @@ /** 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 +client API of the Kernel Hardware Configuration Repository (HCR). +It provides accessor functions to retrieve settings held by the HCR and may be +called by kernel components from with in thread context. + +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. +that clients can include to gain access to all IDs for the BSP. IDs for settings +that are internal to a component and not used by others are defined in a file +private to that component. + +The HCR supports a number of setting repositories and searches them in a defined +order, always returns the first setting found matching the ID or criteria. +This allows setting values to be overriden by more recent repositories created +during platform development and product creation. */ namespace HCR { @@ -75,7 +83,7 @@ }; /** The setting Identifier type. A class used to uniquely identify a - setting in the HCR. Used in calls to HCR API. + setting in the HCR. Used in calls to HCR API to retrieve one setting. */ class TSettingId : public SSettingId { @@ -120,10 +128,11 @@ /** - Retrieve settings of built in types from the HCR. - - @param aId The setting identifier - @param aValue The retrieved setting data value + Retrieve a word size integer setting value from the HCR. + On error aValue is undefined. + + @param aId in: The setting identifier + @param aValue out: The retrieved setting data value @return KErrNone if successful, output parameters valid KErrNotFound if aId is not a known setting ID @@ -140,23 +149,74 @@ IMPORT_C TInt GetInt(const TSettingId& aId, TInt32& aValue); IMPORT_C TInt GetInt(const TSettingId& aId, TInt64& aValue); + /** + Retrieve a boolean setting value from the HCR. + On error aValue is undefined. + + @param aId in: The setting identifier + @param aValue out: 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. + Otherwise one of the other system-wide error codes. + + @pre Call from thread context, during Init1 or later + */ IMPORT_C TInt GetBool(const TSettingId& aId, TBool& aValue); + /** + Retrieve an word size unsigned integer setting value from the HCR. + On error aValue is undefined. + + @param aId in: The setting identifier + @param aValue out: 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. + Otherwise one of the other system-wide error codes. + + @pre Call from thread context, during Init1 or later + */ 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); + /** + Retrieve a word size linear address setting value from the HCR. + On error aValue is undefined. + + @param aId in: The setting identifier + @param aValue out: 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. + Otherwise one of the other system-wide error codes. + + @pre Call from thread context, during Init1 or later + */ IMPORT_C TInt GetLinAddr(const TSettingId& aId, TLinAddr& aValue); + /** - Retrieve a binary data (ETypeBinData) setting from the HCR. + Retrieve a large binary data setting value from the HCR. The value + is copied into the supplied descriptor buffer. + On error the descriptor and output arguments have undefined values. - @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 - + @param aId in: The setting identifier + @param aValue inout: A pre-allocated descriptor to hold the value @return KErrNone if successful and aValue has been set KErrNotFound if aId is not a known setting ID @@ -170,15 +230,39 @@ @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. + Retrieve a large binary data setting value from the HCR. The value is copied + into the supplied byte array buffer. + On error the buffer and output arguments have undefined values. + + @param aId in: The setting identifier + @param aMaxLen in: The maximum value length that can be stored in the buffer + @param aValue inout: The address of a pre-allocated buffer to hold the value + @param aLen out: Contains the length of the setting value written - @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 + Otherwise one of the other system-wide error codes. + + @pre Call from thread context, during Init1 or later + */ + IMPORT_C TInt GetData(const TSettingId& aId, TUint16 aMaxLen, + TUint8* aValue, TUint16& aLen); + + /** + Retrieve an 8 bit character string setting from the HCR. The value + is copied into the supplied descriptor buffer. Note the string is not zero + terminated. + On error the descriptor and output arguments have undefined values. + + @param aId in: The setting identifier + @param aValue inout: A pre-allocated descriptor to hold the value @return KErrNone if successful and aValue has been set KErrNotFound if aId is not a known setting ID @@ -192,17 +276,41 @@ @pre Call from thread context, during Init1 or later */ IMPORT_C TInt GetString(const TSettingId& aId, TDes8& aValue); + + /** + Retrieve an 8 bit character string setting from the HCR. The value + is copied into the byte array buffer. Note the string is not zero + terminated. + On error the descriptor and output arguments have undefined values. + + @param aId in: The setting identifier + @param aMaxLen in: The maximum value length that can be stored in the buffer + @param aValue inout: The address of a pre-allocated buffer to hold the value + @param aLen out: 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 + Otherwise one of the other system-wide error codes. + + @pre Call from thread context, during Init1 or later + */ 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. + Retrieve an array of signed integers from the HCR. The value + is copied into the byte array buffer. + On error the descriptor and output arguments have undefined values. - @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 + @param aId in: The setting identifier + @param aMaxLen in: The maximum value length that can be stored in the buffer + @param aValue inout: The address of a pre-allocated word array to hold the value + @param aLen out: Contains the length, in bytes of the setting value written @return KErrNone if successful and aValue has been set KErrNotFound if aId is not a known setting ID @@ -221,26 +329,35 @@ TUint32* aValue, TUint16& aLen); /** - Retrieve multiple simple settings from the Hardware Configuration + Retrieve multiple word sized settings from the Hardware Configuration Repository in one call. This method can be used for all settings of size 4 - bytes or less (i.e those with a type in 0x0000ffff). - + bytes or less (i.e those with a type less than 0x0000ffff). + The caller is responsible for pre-allocating the arrays supplied. Note the + array of setting IDs (aIds) supplied by the client must be ordered with + aIds[0] containing the lowest and aIds[aNum-1] the highest. Undefined + behaviour will result if this pre-condition is not met. + + On successful return the client will need to check the number found (return + value) matches their needs and cast each value in the aValues + array to the correct type before use. The correct type is either known at + compile time by the caller or determined from aTypes, if supplied. + + When an overall error is returned from the function the output arrays have + undefined values. + @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: A mandatory array supplied by the user which is populated by error - codes for each setting. If no error found for the setting then - KErrNone(=0) is written - setting. - Possible error codes: - KErrArgument if the setting has size larger than - four bytes - KErrNotFound if the setting is not found - KErrNone no any errors reported for this setting + @param aIds in: An ordered array of setting identifiers to retrieve + @param aValues inout: An array of values, populated on exit + @param aTypes inout: An optional array of type enumerations, populated on + exit describing the type of each setting found. + May be 0 if client is not interested + @param aErrors inout: An array of search errors for each setting populated + on exit. If no error found for the setting then KErrNone + is written. Possible error codes: + KErrArgument the setting is not of a suitable type + KErrNotFound the setting is not found + KErrNone when setting found @return Zero or positive number of settings found, -ve on error @@ -260,11 +377,12 @@ /** 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. + obtain the setting size should a buffer need to be allocated. + On error the output arguments are undefined. - @param aId The setting identifier - @param aType The type enumeration of found setting - @param aLen The length in bytes of found setting + @param aId in: The setting identifier + @param aType out: The type enumeration of the found setting + @param aLen out: The length in bytes of the found setting @return KErrNone if successful, output parameters valid KErrNotFound if aId is not a known setting ID @@ -279,14 +397,16 @@ 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. - + Retrieve the number of unique ettings 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. + The method carries out a search to return the total number of unique setting + records found across all HCR repositories for a given category. It does not + count settings that are duplicate from being redefined in different + repositories. + The function is particularly useful for open-ended categories were the + run-time client can not predict the number of settings prvisioned. + @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 @@ -300,22 +420,32 @@ 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 should any be larger than - 4 bytes. - - @param aCatUid in: The setting identifier category to use in the search + Retrieve details of all the settings (ids, types and sizes) in one + particular category. This function can be used by clients to obtain the + number of, ids, sizes and types of all the settings in a category. + It allows a client to alloc buffers for other calls to the HCR to retrieve + the values of these settings. + + On successful return the client will need to check the number found (return + value) matches the expected number. When there are more defined in + the category than was able to be returned, i.e. when number found + exceeded aMaxNum then aMaxNum is returned. + + When an overall error is returned from the function the output arrays have + undefined values. + + @param aCat in: The setting category to search for @param aMaxNum in: The maximum number of settings to return. It is also the size of the arrays in the following arguments - @param aKeyIds inout: Client supplied array populated on exit. Large + @param aKeyIds 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. + enumerations on exit. Array address may be 0 if + client is not interested. @param aLens inout: Client supplied array populated with setting lengths - on exit. May be 0 if client is not interested. + on exit for those settings with a type > 0x0000ffff. + When less than this 0 is set in the aLens array element. + Array address may be 0 if client is not interested. @return Zero or positive number of settings found in category, -ve on error KErrArgument if some parameters are wrong(i.e. aErrors is a null @@ -331,14 +461,18 @@ TElementId aKeyIds[], 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: + Retrieve details of all the settings (ids, types and sizes) in one + particular category who's key ID matches the supplied bit pattern/mask. + This function can be used by clients to obtain the number of, ids, sizes + and types of all the settings in a category. It allows a client to alloc + buffers for other calls to the HCR to retrieve the values of these settings. + + This search method allows categories to contain structured settings + i.e. row/column structured or record based categories as might be used + for configuration data of a hardware service provider. + + The caller supplies the category to search, a setting key ID mask and the + pattern to match. Setting keys that satisfy this logic are returned: ((elementID & aElementMask) == (aPattern & aElementMask)) For example, a set of driver capability structures might be encoded into @@ -348,21 +482,31 @@ to retrieve key fields of all records supply: aElemMask = 0x000000ff, aPattern = 0x******01 (* = dont care) + + On successful return the client will need to check the number found (return + value) matches the expected number. When there are more defined in + the category than was able to be returned, i.e. when number found + exceeded aMaxNum then aMaxNum is returned. + + When an overall error is returned from the function the output arrays have + undefined values. @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 aElemMask in: The bits in the Element ID to be checked against + @param aMask in: The bits in the Element ID to be checked against aPattern @param aPattern in: Identified the bits that must be set for a setting to be returned in the search - @param aKeyIds inout: Client supplied array populated on exit. Large + @param aKeyIds 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. + @param aTypes inout: Client supplied array populated with setting types + enumerations on exit. Array address may be 0 if + client is not interested. + @param aLens inout: Client supplied array populated with setting lengths + on exit for those settings with a type > 0x0000ffff. + When less than this 0 is set in the aLens array element. + Array address may be 0 if client is not interested. @return Zero or positive number of settings found in category, -ve on error KErrArgument if some parameters are wrong(i.e. aErrors is a null