Loading...
Searching...
No Matches
Information areas

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

Collaboration diagram for Information areas:

## Topics

| 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_FOREACH_INFOFIELD(fru, atype, f, idx)
| Iterate through all info area standard fields within the given atype info area of the given fru.
#define | FRU_FOREACH_INFOCUSTOM(fru, atype, f, idx)
| Iterate through all info area custom fields within the given atype info area of the given fru.
#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?
#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_INFOCUSTOM

#define FRU_FOREACH_INFOCUSTOM | ( |  | fru,
|  |  | atype,
|  |  | f,
|  |  | idx )

Iterate through all info area custom fields within the given atype info area of the given fru.

Use f as the field pointer, and \t idx as the index counter.

Make sure f is declared as fru_field_t. Do NOT declare idx.

Example

fru_t * fru = fru_init(NULL);
fru_field_t * field;
FRU_FOREACH_INFOCUSTOM(fru, FRU_CHASSIS_INFO, field, i) {
// Here field is non-NULL and points to a fru_field_t structure
// corresponding to the custom field at index i in
// Chassis Info area within fru
}
fru_init
fru_t * fru_init(fru_t *fru)
Initialize/allocate a fru structure.
FRU_CHASSIS_INFO
@ FRU_CHASSIS_INFO
Chassis information area.
Definition fru.h:522
FRU_FOREACH_INFOCUSTOM
#define FRU_FOREACH_INFOCUSTOM(fru, atype, f, idx)
Iterate through all info area custom fields within the given atype info area of the given fru.
Definition fru.h:247
fru_field_t
A generic input (decoded) field structure.
Definition fru.h:347
fru_t
Exploded/decoded FRU data structure.
Definition fru.h:574

## FRU_FOREACH_INFOFIELD

#define FRU_FOREACH_INFOFIELD | ( |  | fru,
|  |  | atype,
|  |  | f,
|  |  | idx )

Iterate through all info area standard fields within the given atype info area of the given fru.

Use f as the field pointer, and \t idx as the index counter.

Make sure f is declared as fru_field_t. Do NOT declare idx.

Example

fru_t * fru = fru_init(NULL);
fru_field_t * field;
FRU_FOREACH_INFOFIELD(fru, FRU_CHASSIS_INFO, field, i) {
// Here field is non-NULL and points to a fru_field_t structure
// correspondigh to the standard field at index i in
// Chassis Info area within fru
}
FRU_FOREACH_INFOFIELD
#define FRU_FOREACH_INFOFIELD(fru, atype, f, idx)
Iterate through all info area standard fields within the given atype info area of the given fru.
Definition fru.h:223

## 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_area_type_t
fru_area_type_t
FRU area types.
Definition fru.h:519
FRU_FOREACH_INFOIDX
#define FRU_FOREACH_INFOIDX(it)
Iterate through all info area indices using it as an iterator.
Definition fru.h:202
FRU_INFO_AREAS
#define FRU_INFO_AREAS
Number of standard 'info' areas.
Definition fru.h:146
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 inv...
Definition fru.h:163

## 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
#define FRU_INFOIDX(a)
Get the info area index from an area type enum name.
Definition fru.h:184

## 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.

See also FRU_REAL_FE(), FRU_FE_IS_REAL(), FRU_FIELD_IS_REAL_ENC(), FRU_FIELD_IS_AUTO_ENC()

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:
  - FEAREANOTSUP
  - FEAREABADTYPE
  - FENOFIELD

## 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:
  - FEAREANOTSUP
  - FEAREABADTYPE
  - FENOFIELD

## 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