Definitions common for all three Info areas. More...

Collaboration diagram for Information areas:

Modules
	Chassis Information Area
	Definitions related to Chassis Info Area.

	Board Information Area
	Definitions related to Board Info Area.

	Product area
	Definitions related to Product Info Area.

Data Structures
struct	fru_field_t
	A generic input (decoded) field structure. More...

Macros
#define	FRU_INFO_AREAS
	Number of standard 'info' areas.

#define	FRU_FIRST_INFO_AREA
	Index of the first 'info' area.

#define	FRU_LAST_INFO_AREA
	Index of the first 'info' area.

#define	FRU_IS_INFO_AREA(atype)
	Check if atype is an information area type.

#define	FRU_ATYPE_TO_INFOIDX(atype)
	Convert an area type atype into an information area index or to -1 if atype is not an info area type.

#define	FRU_INFOIDX_TO_ATYPE(idx)
	Convert an info area index idx into a full-range area type or to (fru_area_type_t)(-1) if idx was invalid.

#define	FRU_INFOIDX(a)
	Get the info area index from an area type enum name.

#define	FRU_FOREACH_INFOIDX(it)
	Iterate through all info area indices using it as an iterator.

#define	FRU_REAL_FE(t)
	Convert a fru_field_enc_t value to an index to a FRU_FE_REALCOUNT-sized array.

#define	FRU_FE_FROMREAL(t)
	Convert an index to a FRU_FE_REALCOUNT-sized array to a fru_field_enc_t value.

#define	FRU_FE_IS_REAL(t)
	Check if t is a 'real' encoding type? (One that is defined by FRU specification)

#define	FRU_FIELD_IS_REAL_ENC(f)
	Check if field f is non-NULL and has a real encoding.

#define	FRU_FIELD_IS_AUTO_ENC(f)
	Check if field f is non-NULL and has an auto encoding.

#define	FRU_MAX_FIELD_COUNT
	Max mandatory field count among all info areas.

Typedefs
typedef void *	fru_custom_t
	A list of custom fields of an info area.

Enumerations
enum	fru_field_enc_t { FRU_FE_EMPTY , FRU_FE_BASE , FRU_FE_BINARY , FRU_FE_MIN , FRU_FE_BCDPLUS , FRU_FE_6BITASCII , FRU_FE_TEXT , FRU_FE_MAX , FRU_FE_AUTO , FRU_FE_UNKNOWN , FRU_FE_PRESERVE , FRU_FE_TOTALCOUNT , FRU_FE_REALCOUNT }
	Field encoding type. More...

Functions
bool	fru_setfield (fru_field_t field, fru_field_enc_t encoding, const char string)
	Copy string to the given field, perform length check according to selected encoding, truncate if needed.

bool	fru_setfield_binary (fru_field_t field, const void buf, size_t size)
	Copy a binary input buffer into the given field, perform length check, truncate if needed.

fru_field_t *	fru_getfield (const fru_t *fru, fru_area_type_t atype, size_t index)
	Get a pointer to a mandatory field in the info area of the given type in the given fru structure.

fru_field_t *	fru_add_custom (fru_t fru, fru_area_type_t atype, size_t index, fru_field_enc_t encoding, const char string)
	Add a custom field to the given area type in the given fru structure.

fru_field_t *	fru_get_custom (const fru_t *fru, fru_area_type_t atype, size_t index)
	Get a pointer to a custom data field in the area of the given type in the given fru structure.

bool	fru_delete_custom (fru_t *fru, fru_area_type_t atype, size_t index)
	Delete a custom data field in the area of the given type in the given fru structure.

Detailed Description

Definitions common for all three Info areas.

Macro Definition Documentation

◆ FRU_ATYPE_TO_INFOIDX

#define FRU_ATYPE_TO_INFOIDX ( atype )

Convert an area type atype into an information area index or to -1 if atype is not an info area type.

◆ FRU_FE_FROMREAL

#define FRU_FE_FROMREAL ( t )

Convert an index to a FRU_FE_REALCOUNT-sized array to a fru_field_enc_t value.

Parameters

t	an unsigned integer value

◆ FRU_FE_IS_REAL

#define FRU_FE_IS_REAL ( t )

Check if t is a 'real' encoding type? (One that is defined by FRU specification)

Parameters

t	fru_field_enc_t, a field encoding type value

◆ FRU_FIELD_IS_AUTO_ENC

#define FRU_FIELD_IS_AUTO_ENC ( f )

Check if field f is non-NULL and has an auto encoding.

Parameters

f	fru_field_t *, A field pointer

◆ FRU_FIELD_IS_REAL_ENC

#define FRU_FIELD_IS_REAL_ENC ( f )

Check if field f is non-NULL and has a real encoding.

Parameters

f	fru_field_t *, A field pointer

◆ FRU_FIRST_INFO_AREA

#define FRU_FIRST_INFO_AREA

Index of the first 'info' area.

◆ FRU_FOREACH_INFOIDX

#define FRU_FOREACH_INFOIDX ( it )

Iterate through all info area indices using it as an iterator.

It is recommended to declare it as size_t.

Example

const char * const area_names[FRU_INFO_AREAS] = { "Chassis", "Board", "Product" };
size_t infoidx;
FRU_FOREACH_INFOIDX(infoidx) {
    fru_area_type_t atype = FRU_INFOIDX_TO_ATYPE(index);
    if (fru->present[atype]) {
        printf("%s Information Area is present\n", area_names[index]);
    }
}

◆ FRU_INFO_AREAS

#define FRU_INFO_AREAS

Number of standard 'info' areas.

◆ FRU_INFOIDX

#define FRU_INFOIDX ( a )

Get the info area index from an area type enum name.

That is, instead of FRU_ATYPE_INFOIDX(FRU_PRODUCT_INFO) you may write FRU_INFOIDX(PRODUCT).

This is particularly useful in array initializers:

Example

int magic_number[FRU_INFO_AREAS] = {
    [FRU_INFOIDX(CHASSIS)] = 42,
    [FRU_INFOIDX(BOARD)] = 1337,
    [FRU_INFOIDX(PRODUCT)] = 1984,
};

◆ FRU_INFOIDX_TO_ATYPE

#define FRU_INFOIDX_TO_ATYPE ( idx )

Convert an info area index idx into a full-range area type or to (fru_area_type_t)(-1) if idx was invalid.

◆ FRU_IS_INFO_AREA

#define FRU_IS_INFO_AREA ( atype )

Check if atype is an information area type.

◆ FRU_LAST_INFO_AREA

#define FRU_LAST_INFO_AREA

Index of the first 'info' area.

◆ FRU_MAX_FIELD_COUNT

#define FRU_MAX_FIELD_COUNT

Max mandatory field count among all info areas.

◆ FRU_REAL_FE

#define FRU_REAL_FE ( t )

Convert a fru_field_enc_t value to an index to a FRU_FE_REALCOUNT-sized array.

Parameters

t	fru_field_enc_t, a field encoding type value

Typedef Documentation

◆ fru_custom_t

typedef void* fru_custom_t

A list of custom fields of an info area.

Enumeration Type Documentation

◆ fru_field_enc_t

enum fru_field_enc_t

Field encoding type.

This enum contains values as per Section 13 of IPMI FRU Specification, as well as some extensions used solely by the functions of this library and not saved into the output binary file or buffer.

Anything outside the range of FRU_FE_MIN to FRU_FE_MAX is an extension.

Enumerator
FRU_FE_EMPTY	The field is empty. The default state of a fru_field_t variable when it is zeroed. Fields of this encoding will be saved as empty even if their `fru_field_t.val` string is not.
FRU_FE_BASE	Base encoding, starting at which all the binary FRU file field encodings are mapped.
FRU_FE_BINARY	Encode the field as binary, the value is a hex string (e.g., 1337C0DE)
FRU_FE_MIN	The minumum non-auto (real) encoding, equals FRU_FE_BINARY.
FRU_FE_BCDPLUS	Encode the field as BCD+, the value may only contain digits 0-9, space, dash, or period.
FRU_FE_6BITASCII	Encode the field as 6-bit ASCII, the value may only contain characters per Table 13-1 of IPMI FRU Specification.
FRU_FE_TEXT	Encode the field as plain text (ASCII+Latin1). Only English is currently supported, see Section 13 of IPMI FRU Specification
FRU_FE_MAX	Maximim valid 'real' field encoding, equals FRU_FE_TEXT.
FRU_FE_AUTO	When saving, detect the encoding automatically based on the character range of `fru_field_t.val`
FRU_FE_UNKNOWN	Field encoding couldn't be detected or wasn't set.
FRU_FE_PRESERVE	Preserve the field encoding as it was, fail if impossible. This is a virtual encoding for use with fru_setfield() only
FRU_FE_TOTALCOUNT	Total count of all field encodings (including the extensions)
FRU_FE_REALCOUNT	Total count of standard field encodings (not including the extensions)

Function Documentation

◆ fru_add_custom()

fru_field_t * fru_add_custom	(	fru_t *	fru,
		fru_area_type_t	atype,
		size_t	index,
		fru_field_enc_t	encoding,
		const char *	string
	)

Add a custom field to the given area type in the given fru structure.

Allocates a new custom fields list entry for the given area type within the decoded fru structure and calls fru_setfield() on it with the given input string.

The new record is added/inserted at the given index in the list.

Automatically sets fru->presence[atype] = true

Parameters

[in]	fru	The decoded FRU information structure to modify.
[in]	index	Index in the custom record list at which to add the new record. Specify FRU_LIST_TAIL to add the new record at the end of the list, or FRU_LIST_HEAD to insert it at the head.
[in]	atype	Type of the area to modify in fru. Only supports areas that can have custom fields by specification, namely: FRU_CHASSIS_INFO FRU_BOARD_INFO FRU_PRODUCT_INFO
[in]	encoding	Desired encoding. Can't use FRU_FE_PRESERVE here. Use only the standard encodings here or FRU_FE_EMPTY to add an empty field to be set later with fru_setfield()
[in]	string	The input string to add as a custom field.

Returns: A pointer to the added field, see fru_setfield() for info on possible errors

Return values

NULL	Failure, additionally may set fru_errno.code to: FEAREANOTSUP FEAREABADTYPE

◆ fru_delete_custom()

bool fru_delete_custom	(	fru_t *	fru,
		fru_area_type_t	atype,
		size_t	index
	)

Delete a custom data field in the area of the given type in the given fru structure.

Finds the custom field at the given index and deletes it from the list, deallocates memory.

Parameters

[in]	fru	The decoded FRU information structure to modify.
[in]	atype	Type of the area to modify in fru. Only supports areas that can have custom fields by specification, namely: FRU_CHASSIS_INFO FRU_BOARD_INFO FRU_PRODUCT_INFO
[in]	index	The index of the custom field to fetch

Returns: Success status

Return values

true	The requested cusom field has been deleted
false	There was an error, see fru_errno

◆ fru_get_custom()

fru_field_t * fru_get_custom	(	const fru_t *	fru,
		fru_area_type_t	atype,
		size_t	index
	)

Get a pointer to a custom data field in the area of the given type in the given fru structure.

Finds the custom field at the given index and returns a pointer to it, so that fru_setfield() could be used on it.

Parameters

[in]	fru	The decoded FRU information structure to search in.
[in]	atype	Type of the area to search in fru. Only supports areas that can have custom fields by specification, namely: FRU_CHASSIS_INFO FRU_BOARD_INFO FRU_PRODUCT_INFO
[in]	index	The index of the custom field to fetch

Returns

A pointer to the custom field at the requested index or NULL in the event of failure. For the latter case fru_errno.code is set to:

◆ fru_getfield()

fru_field_t * fru_getfield	(	const fru_t *	fru,
		fru_area_type_t	atype,
		size_t	index
	)

Get a pointer to a mandatory field in the info area of the given type in the given fru structure.

Finds the mandatory string field at the given index and returns a pointer to it, so that fru_setfield() could be used on it.

Only gets fru_field_t compatible fields. Doesn't work on area-specific non-string fields like board.tv, board.lang, chassis.type, etc.

The first fru_field_t compatible field in any info area is considered to be at index 0.

This function is useful when you want to iterate over all the string-like standard fields and don't care much about their designation (or probably define those associations externally).

You may as well use it to get specific fields by specifying as index the values of fru_chassis_field_t, fru_board_field_t, or fru_prod_field_t depending on which atype is specified. On the other hand, for such a case it may be easier to directly access the corresponding field in an area structure (e.g., fru->board.serial).

Parameters

[in]	fru	The decoded FRU information structure to search in
[in]	atype	Type of the area to search in fru. Only supports 'info' areas with mandatory fields, namely: FRU_CHASSIS_INFO FRU_BOARD_INFO FRU_PRODUCT_INFO
[in]	index	The index of the custom field to fetch

Returns

A pointer to the mandatory field at the requested index or NULL in the event of failure. For the latter case fru_errno.code is set to:

◆ fru_setfield()

bool fru_setfield	(	fru_field_t *	field,
		fru_field_enc_t	encoding,
		const char *	string
	)

Copy string to the given field, perform length check according to selected encoding, truncate if needed.

Attempt will be made to encode the input string using the requested encoding unless it is FRU_FE_PRESERVE, in which event the function will attempt to preserve any valid encoding set in the target field. If the encoding in the target field in not valid then the function will behave as if encoding was set to FRU_FE_AUTO.

If the encoding attempt succeeds, the input string and the requested encoding value will be copied into the given field. The string will be truncated to fit and the truncation event will be indicated via fru_errno.code as FE2BIG along with success return code. Please call fru_clearerr() before the call to avoid false positive checks for truncation.

Parameters

[in,out]	field	Pointer to a decoded field (typically inside a member of fru_t)
[in]	encoding	Desired encoding.
[in]	string	The input string to set the field to.

Returns: Success status

Return values

true	Success, check fru_errno.code for FE2BIG to see if data was truncated
false	Failure, check fru_errno for details

◆ fru_setfield_binary()

bool fru_setfield_binary	(	fru_field_t *	field,
		const void *	buf,
		size_t	size
	)

Copy a binary input buffer into the given field, perform length check, truncate if needed.

Unlike fru_setfield() that takes an input string and an encoding type, this function takes a binary buffer and its size as an input. It the converts the buffer into a hex string, and sets the field encoding type to FRU_FE_BINARY.

If the input buffer size is too large to fit into a field (that is, more than 63 bytes), only the data that can fit will be taken, and the truncation event will be indicated via fru_errno.code as FE2BIG along with a success return code. Please call fru_clearerr() before the call to avoid false positive checks for truncation.

Parameters

[in,out]	field	Pointer to a decoded field (typically inside a member of fru_t)
[in]	buf	The source binary buffer
[in]	size	The source buffer size in bytes

Returns: Success status

Return values

true	Success, check fru_errno.code for FE2BIG to see if data was truncated
false	Failure, check fru_errno for details

Modules

Data Structures

Macros

Typedefs

Enumerations

Functions

Detailed Description

Macro Definition Documentation

◆ FRU_ATYPE_TO_INFOIDX

◆ FRU_FE_FROMREAL

◆ FRU_FE_IS_REAL

◆ FRU_FIELD_IS_AUTO_ENC

◆ FRU_FIELD_IS_REAL_ENC

◆ FRU_FIRST_INFO_AREA

◆ FRU_FOREACH_INFOIDX

◆ FRU_INFO_AREAS

◆ FRU_INFOIDX

◆ FRU_INFOIDX_TO_ATYPE

◆ FRU_IS_INFO_AREA

◆ FRU_LAST_INFO_AREA

◆ FRU_MAX_FIELD_COUNT

◆ FRU_REAL_FE

Typedef Documentation

◆ fru_custom_t

Enumeration Type Documentation

◆ fru_field_enc_t

Function Documentation

◆ fru_add_custom()

◆ fru_delete_custom()

◆ fru_get_custom()

◆ fru_getfield()

◆ fru_setfield()

◆ fru_setfield_binary()