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)
20 Kernel side client API for Hardware Configuration Repository (HCR).
21 The HCR service provides access to hardware settings defined for the base port.
22 This API is used by kernel side components such as PDDs, hardware service
23 providers and other kernel extensions.
35 // -- INCLUDES ----------------------------------------------------------------
44 // -- CLASSES -----------------------------------------------------------------
47 The HCR namespace contains all the types and APIs that make up the
48 client API of the Kernel Hardware Configuration Repository (HCR).
49 It provides accessor functions to retrieve settings held by the HCR and may be
50 called by kernel components from with in thread context.
52 The _published_ Setting IDs available for use with this API can be found
53 in the BSP exported header 'hcrconfig.h'. This provides the top-level header
54 that clients can include to gain access to all IDs for the BSP. IDs for settings
55 that are internal to a component and not used by others are defined in a file
56 private to that component.
58 The HCR supports a number of setting repositories and searches them in a defined
59 order, always returns the first setting found matching the ID or criteria.
60 This allows setting values to be overriden by more recent repositories created
61 during platform development and product creation.
66 /** Maximum length of a large setting type, in bytes */
67 static const TInt KMaxSettingLength = 512;
70 /** Setting category identifier type */
71 typedef TUint32 TCategoryUid;
73 /** Setting element identifier type */
74 typedef TUint32 TElementId;
76 /** The setting Identifier structure. Used to create static initialised
77 arrys for use with multiple setting retrieval calls.
81 TCategoryUid iCat; //!< Allocated UID for setting category
82 TElementId iKey; //!< Element indetifier for setting in category
85 /** The setting Identifier type. A class used to uniquely identify a
86 setting in the HCR. Used in calls to HCR API to retrieve one setting.
88 class TSettingId : public SSettingId
93 TSettingId (TCategoryUid aCat, TElementId aKey)
94 { iCat = aCat; iKey = aKey; };
95 TSettingId (const SSettingId& aId)
96 { iCat = aId.iCat; iKey = aId.iKey; };
97 TSettingId& operator= (const SSettingId& rhs)
98 { iCat = rhs.iCat; iKey = rhs.iKey; return *this; }
102 /** The setting types supported. The types are shown in two groups: Word
103 size - a maximum of 4 bytes; and ii) Large size - types exceeding 4 bytes
108 ETypeUndefined = 0, //!< Type unknown/not set
110 // Word size settings
111 ETypeInt32 = 0x00000001, //!< 32bit signed integer
112 ETypeInt16 = 0x00000002, //!< 16bit signed integer
113 ETypeInt8 = 0x00000004, //!< 8bit signed integer
114 ETypeBool = 0x00000008, //!< 32bit boolean value
115 ETypeUInt32 = 0x00000010, //!< 32bit unsigned integer
116 ETypeUInt16 = 0x00000020, //!< 16bit unsigned integer
117 ETypeUInt8 = 0x00000040, //!< 8bit unsigned integer
118 ETypeLinAddr = 0x00000100, //!< 32bit virtual address
121 ETypeBinData = 0x00010000, //!< Raw binary data (TUint8 array)
122 ETypeText8 = 0x00020000, //!< String data (TText8 array)
123 ETypeArrayInt32 = 0x00040000, //!< 32bit signed integer array
124 ETypeArrayUInt32 = 0x00080000, //!< 32bit unsigned integer array
125 ETypeInt64 = 0x01000000, //!< 64bit signed integer
126 ETypeUInt64 = 0x02000000, //!< 64bit unsigned integer
131 Retrieve a word size integer setting value from the HCR.
132 On error aValue is undefined.
134 @param aId in: The setting identifier
135 @param aValue out: The retrieved setting data value
137 @return KErrNone if successful, output parameters valid
138 KErrNotFound if aId is not a known setting ID
139 KErrArgument if the setting identified is not the correct type
140 KErrNotReady if the HCR is used before it has been initialised
141 KErrCorrupt if HCR finds a repository to be corrupt
142 KErrGeneral if an internal failure occurs, see trace.
143 Otherwise one of the other system-wide error codes.
145 @pre Call from thread context, during Init1 or later
147 IMPORT_C TInt GetInt(const TSettingId& aId, TInt8& aValue);
148 IMPORT_C TInt GetInt(const TSettingId& aId, TInt16& aValue);
149 IMPORT_C TInt GetInt(const TSettingId& aId, TInt32& aValue);
150 IMPORT_C TInt GetInt(const TSettingId& aId, TInt64& aValue);
153 Retrieve a boolean setting value from the HCR.
154 On error aValue is undefined.
156 @param aId in: The setting identifier
157 @param aValue out: The retrieved setting data value
159 @return KErrNone if successful, output parameters valid
160 KErrNotFound if aId is not a known setting ID
161 KErrArgument if the setting identified is not the correct type
162 KErrNotReady if the HCR is used before it has been initialised
163 KErrCorrupt if HCR finds a repository to be corrupt
164 KErrGeneral if an internal failure occurs, see trace.
165 Otherwise one of the other system-wide error codes.
167 @pre Call from thread context, during Init1 or later
169 IMPORT_C TInt GetBool(const TSettingId& aId, TBool& aValue);
172 Retrieve an word size unsigned integer setting value from the HCR.
173 On error aValue is undefined.
175 @param aId in: The setting identifier
176 @param aValue out: The retrieved setting data value
178 @return KErrNone if successful, output parameters valid
179 KErrNotFound if aId is not a known setting ID
180 KErrArgument if the setting identified is not the correct type
181 KErrNotReady if the HCR is used before it has been initialised
182 KErrCorrupt if HCR finds a repository to be corrupt
183 KErrGeneral if an internal failure occurs, see trace.
184 Otherwise one of the other system-wide error codes.
186 @pre Call from thread context, during Init1 or later
188 IMPORT_C TInt GetUInt(const TSettingId& aId, TUint8& aValue);
189 IMPORT_C TInt GetUInt(const TSettingId& aId, TUint16& aValue);
190 IMPORT_C TInt GetUInt(const TSettingId& aId, TUint32& aValue);
191 IMPORT_C TInt GetUInt(const TSettingId& aId, TUint64& aValue);
194 Retrieve a word size linear address setting value from the HCR.
195 On error aValue is undefined.
197 @param aId in: The setting identifier
198 @param aValue out: The retrieved setting data value
200 @return KErrNone if successful, output parameters valid
201 KErrNotFound if aId is not a known setting ID
202 KErrArgument if the setting identified is not the correct type
203 KErrNotReady if the HCR is used before it has been initialised
204 KErrCorrupt if HCR finds a repository to be corrupt
205 KErrGeneral if an internal failure occurs, see trace.
206 Otherwise one of the other system-wide error codes.
208 @pre Call from thread context, during Init1 or later
210 IMPORT_C TInt GetLinAddr(const TSettingId& aId, TLinAddr& aValue);
214 Retrieve a large binary data setting value from the HCR. The value
215 is copied into the supplied descriptor buffer.
216 On error the descriptor and output arguments have undefined values.
218 @param aId in: The setting identifier
219 @param aValue inout: A pre-allocated descriptor to hold the value
221 @return KErrNone if successful and aValue has been set
222 KErrNotFound if aId is not a known setting ID
223 KErrArgument if the setting identified is not the correct type
224 KErrNotReady if the HCR is used before it has been initialised
225 KErrCorrupt if HCR finds a repository to be corrupt
226 KErrTooBig if the setting is larger than the supplied buffer
227 KErrGeneral if an internal failure occurs, see trace
228 Otherwise one of the other system-wide error codes.
230 @pre Call from thread context, during Init1 or later
232 IMPORT_C TInt GetData(const TSettingId& aId, TDes8& aValue);
235 Retrieve a large binary data setting value from the HCR. The value is copied
236 into the supplied byte array buffer.
237 On error the buffer and output arguments have undefined values.
239 @param aId in: The setting identifier
240 @param aMaxLen in: The maximum value length that can be stored in the buffer
241 @param aValue inout: The address of a pre-allocated buffer to hold the value
242 @param aLen out: Contains the length of the setting value written
244 @return KErrNone if successful and aValue has been set
245 KErrNotFound if aId is not a known setting ID
246 KErrArgument if the setting identified is not the correct type
247 KErrNotReady if the HCR is used before it has been initialised
248 KErrCorrupt if HCR finds a repository to be corrupt
249 KErrTooBig if the setting is larger than the supplied buffer
250 KErrGeneral if an internal failure occurs, see trace
251 Otherwise one of the other system-wide error codes.
253 @pre Call from thread context, during Init1 or later
255 IMPORT_C TInt GetData(const TSettingId& aId, TUint16 aMaxLen,
256 TUint8* aValue, TUint16& aLen);
259 Retrieve an 8 bit character string setting from the HCR. The value
260 is copied into the supplied descriptor buffer. Note the string is not zero
262 On error the descriptor and output arguments have undefined values.
264 @param aId in: The setting identifier
265 @param aValue inout: A pre-allocated descriptor to hold the value
267 @return KErrNone if successful and aValue has been set
268 KErrNotFound if aId is not a known setting ID
269 KErrArgument if the setting identified is not the correct type
270 KErrNotReady if the HCR is used before it has been initialised
271 KErrCorrupt if HCR finds a repository to be corrupt
272 KErrTooBig if the setting is larger than the supplied buffer
273 KErrGeneral if an internal failure occurs, see trace
274 Otherwise one of the other system-wide error codes.
276 @pre Call from thread context, during Init1 or later
278 IMPORT_C TInt GetString(const TSettingId& aId, TDes8& aValue);
281 Retrieve an 8 bit character string setting from the HCR. The value
282 is copied into the byte array buffer. Note the string is not zero
284 On error the descriptor and output arguments have undefined values.
286 @param aId in: The setting identifier
287 @param aMaxLen in: The maximum value length that can be stored in the buffer
288 @param aValue inout: The address of a pre-allocated buffer to hold the value
289 @param aLen out: Contains the length of the setting value written
291 @return KErrNone if successful and aValue has been set
292 KErrNotFound if aId is not a known setting ID
293 KErrArgument if the setting identified is not the correct type
294 KErrNotReady if the HCR is used before it has been initialised
295 KErrCorrupt if HCR finds a repository to be corrupt
296 KErrTooBig if the setting is larger than the supplied buffer
297 KErrGeneral if an internal failure occurs, see trace
298 Otherwise one of the other system-wide error codes.
300 @pre Call from thread context, during Init1 or later
302 IMPORT_C TInt GetString(const TSettingId& aId, TUint16 aMaxLen,
303 TText8* aValue, TUint16& aLen);
306 Retrieve an array of signed integers from the HCR. The value
307 is copied into the byte array buffer.
308 On error the descriptor and output arguments have undefined values.
310 @param aId in: The setting identifier
311 @param aMaxLen in: The maximum value length that can be stored in the buffer
312 @param aValue inout: The address of a pre-allocated word array to hold the value
313 @param aLen out: Contains the length, in bytes of the setting value written
315 @return KErrNone if successful and aValue has been set
316 KErrNotFound if aId is not a known setting ID
317 KErrArgument if the setting identified is not the correct type
318 KErrNotReady if the HCR is used before it has been initialised
319 KErrCorrupt if HCR finds a repository to be corrupt
320 KErrTooBig if the setting is larger than the supplied buffer
321 KErrGeneral if an internal failure occurs, see trace
322 Otherwise one of the other system-wide error codes.
324 @pre Call from thread context, during Init1 or later
326 IMPORT_C TInt GetArray(const TSettingId& aId, TUint16 aMaxLen,
327 TInt32* aValue, TUint16& aLen);
328 IMPORT_C TInt GetArray(const TSettingId& aId, TUint16 aMaxLen,
329 TUint32* aValue, TUint16& aLen);
332 Retrieve multiple word sized settings from the Hardware Configuration
333 Repository in one call. This method can be used for all settings of size 4
334 bytes or less (i.e those with a type less than 0x0000ffff).
335 The caller is responsible for pre-allocating the arrays supplied. Note the
336 array of setting IDs (aIds) supplied by the client must be ordered with
337 aIds[0] containing the lowest and aIds[aNum-1] the highest. Undefined
338 behaviour will result if this pre-condition is not met.
340 On successful return the client will need to check the number found (return
341 value) matches their needs and cast each value in the aValues
342 array to the correct type before use. The correct type is either known at
343 compile time by the caller or determined from aTypes, if supplied.
345 When an overall error is returned from the function the output arrays have
348 @param aNum in: The number of settings to retrieve. It is also the
349 size of the arrays in the following arguments
350 @param aIds in: An ordered array of setting identifiers to retrieve
351 @param aValues inout: An array of values, populated on exit
352 @param aTypes inout: An optional array of type enumerations, populated on
353 exit describing the type of each setting found.
354 May be 0 if client is not interested
355 @param aErrors inout: An array of search errors for each setting populated
356 on exit. If no error found for the setting then KErrNone
357 is written. Possible error codes:
358 KErrArgument the setting is not of a suitable type
359 KErrNotFound the setting is not found
360 KErrNone when setting found
363 @return Zero or positive number of settings found, -ve on error
364 KErrArgument if some parameters are wrong(i.e. aErrors is a null
365 pointer, aNum is negative and so on)
366 KErrCorrupt if HCR finds a repository to be corrupt
367 KErrGeneral if an internal failure occurs, see trace
368 KErrNotReady if the HCR is used before it has been initialised
369 KErrNoMemory if the memory allocation within this function failed
370 Otherwise one of the other system-wide error codes.
372 @pre Call from thread context, during Init1 or later
374 IMPORT_C TInt GetWordSettings(TInt aNum, const SSettingId aIds[],
375 TInt32 aValues[], TSettingType aTypes[], TInt aErrors[]);
379 Retrieve the type and size of a HCR setting. Can be used by clients to
380 obtain the setting size should a buffer need to be allocated.
381 On error the output arguments are undefined.
383 @param aId in: The setting identifier
384 @param aType out: The type enumeration of the found setting
385 @param aLen out: The length in bytes of the found setting
387 @return KErrNone if successful, output parameters valid
388 KErrNotFound if aId is not a known setting ID
389 KErrNotReady if the HCR is used before it has been initialised
390 KErrCorrupt if HCR finds a repository to be corrupt
391 KErrGeneral if an internal failure occurs, see trace
392 Otherwise one of the other system-wide error codes.
394 @pre Call from thread context, during Init1 or later
396 IMPORT_C TInt GetTypeAndSize(const TSettingId& aId,
397 TSettingType& aType, TUint16& aLen);
400 Retrieve the number of unique ettings held in the HCR for one particular
401 category. It allows a client to perpare buffers for other calls to the HCR
402 to retrieve these settings.
403 The method carries out a search to return the total number of unique setting
404 records found across all HCR repositories for a given category. It does not
405 count settings that are duplicate from being redefined in different
407 The function is particularly useful for open-ended categories were the
408 run-time client can not predict the number of settings prvisioned.
410 @param aCatUid in: The setting identifier category to use in the search
412 @return Zero or positive number of settings found in category, -ve on error
413 KErrNotReady if the HCR is used before it has been initialised
414 KErrCorrupt if HCR finds a repository to be corrupt
415 KErrGeneral if an internal failure occurs, see trace
416 Otherwise one of the other system-wide error codes.
418 @pre Call from thread context, during Init1 or later
420 IMPORT_C TInt FindNumSettingsInCategory (TCategoryUid aCatUid);
423 Retrieve details of all the settings (ids, types and sizes) in one
424 particular category. This function can be used by clients to obtain the
425 number of, ids, sizes and types of all the settings in a category.
426 It allows a client to alloc buffers for other calls to the HCR to retrieve
427 the values of these settings.
429 On successful return the client will need to check the number found (return
430 value) matches the expected number. When there are more defined in
431 the category than was able to be returned, i.e. when number found
432 exceeded aMaxNum then aMaxNum is returned.
434 When an overall error is returned from the function the output arrays have
437 @param aCat in: The setting category to search for
438 @param aMaxNum in: The maximum number of settings to return. It is also
439 the size of the arrays in the following arguments
440 @param aKeyIds inout: Client supplied array populated on exit. Large
441 enough to hold all elements in category.
442 @param aTypes inout: Client supplied array populated with setting types
443 enumerations on exit. Array address may be 0 if
444 client is not interested.
445 @param aLens inout: Client supplied array populated with setting lengths
446 on exit for those settings with a type > 0x0000ffff.
447 When less than this 0 is set in the aLens array element.
448 Array address may be 0 if client is not interested.
450 @return Zero or positive number of settings found in category, -ve on error
451 KErrArgument if some parameters are wrong(i.e. aErrors is a null
452 pointer, aNum is negative and so on)
453 KErrNotReady if the HCR is used before it has been initialised
454 KErrCorrupt if HCR finds a repository to be corrupt
455 KErrGeneral if an internal failure occurs, see trace
456 Otherwise one of the other system-wide error codes.
458 @pre Call from thread context, during Init1 or later
460 IMPORT_C TInt FindSettings(TCategoryUid aCatUid, TInt aMaxNum,
461 TElementId aKeyIds[], TSettingType aTypes[], TUint16 aLens[]);
464 Retrieve details of all the settings (ids, types and sizes) in one
465 particular category who's key ID matches the supplied bit pattern/mask.
466 This function can be used by clients to obtain the number of, ids, sizes
467 and types of all the settings in a category. It allows a client to alloc
468 buffers for other calls to the HCR to retrieve the values of these settings.
470 This search method allows categories to contain structured settings
471 i.e. row/column structured or record based categories as might be used
472 for configuration data of a hardware service provider.
474 The caller supplies the category to search, a setting key ID mask and the
475 pattern to match. Setting keys that satisfy this logic are returned:
476 ((elementID & aElementMask) == (aPattern & aElementMask))
478 For example, a set of driver capability structures might be encoded into
479 an element ID where the 24 MSb are the row/record number and the 8 LSb
480 are the column/field index. Thus to retrieve all fields in row 2 supply:
481 aElemMask = 0xffffff00, aPattern = 0x000002**
482 to retrieve key fields of all records supply:
483 aElemMask = 0x000000ff, aPattern = 0x******01
486 On successful return the client will need to check the number found (return
487 value) matches the expected number. When there are more defined in
488 the category than was able to be returned, i.e. when number found
489 exceeded aMaxNum then aMaxNum is returned.
491 When an overall error is returned from the function the output arrays have
494 @param aCat in: The category to retrieve settings for
495 @param aMaxNum in: The maximum number of settings to retrieve. It is also
496 the size of the arrays in the following arguments
497 @param aMask in: The bits in the Element ID to be checked against
499 @param aPattern in: Identified the bits that must be set for a
500 setting to be returned in the search
501 @param aKeyIds inout: Client supplied array populated on exit. Large
502 enough to hold aMaxNum element ids.
503 @param aTypes inout: Client supplied array populated with setting types
504 enumerations on exit. Array address may be 0 if
505 client is not interested.
506 @param aLens inout: Client supplied array populated with setting lengths
507 on exit for those settings with a type > 0x0000ffff.
508 When less than this 0 is set in the aLens array element.
509 Array address may be 0 if client is not interested.
511 @return Zero or positive number of settings found in category, -ve on error
512 KErrArgument if some parameters are wrong(i.e. aErrors is a null
513 pointer, aNum is negative and so on)
514 KErrNotReady if the HCR is used before it has been initialised
515 KErrCorrupt if HCR finds a repository to be corrupt
516 KErrGeneral if an internal failure occurs, see trace
517 KErrNoMemory if the memory allocation within this function failed
518 Otherwise one of the other system-wide error codes.
521 @pre Call from thread context, during Init1 or later
523 IMPORT_C TInt FindSettings(TCategoryUid aCat, TInt aMaxNum,
524 TUint32 aMask, TUint32 aPattern, TElementId aKeyIds[],
525 TSettingType aTypes[], TUint16 aLens[]);