fru.h

Go to the documentation of this file.

 
#pragma once
#include <limits.h>
#include <stdbool.h>
#include <stdint.h>
#include <stdlib.h>
#include <sys/time.h>
#include <sys/types.h>
 
#define LIBFRU_MAJOR    3L 
#define LIBFRU_MINOR    1L 
#define LIBFRU_SUBMINOR 0L 
 
#define LIBFRU_VERSION  (LIBFRU_MAJOR << 16 | \
                         LIBFRU_MINOR << 8 | \
                         LIBFRU_SUBMINOR)
 
/*
 * Private macro definitions.
 *
 * These macros aren't for library users, but they are needed for public
 * interfaces definition.
 *
 * @cond PRIVATE
 */
 
#define fru__zfree(buf) do { \
    int err = errno; /* Prevent errno corruption */ \
    free(buf); \
    (buf) = NULL; \
    errno = err; \
} while(0)
 
#define FRU__BIT(x) (1 << (x))
 
/*
 * Field types per Section 13 of IPMI FRU Specification,
 * in their binary/encoded representation
 */
#define FRU__TYPE_BINARY         0x00
#define FRU__TYPE_BCDPLUS        0x01
#define FRU__TYPE_ASCII_6BIT     0x02
#define FRU__TYPE_TEXT           0x03
 
#define FRU__TYPE_BITS_MASK    0xC0
#define FRU__FIELDLEN(x)   ((size_t)(((x) & ~FRU__TYPE_BITS_MASK)))
 
#define FRU__FIELDMAXLEN       FRU__FIELDLEN(UINT8_MAX)
/*
 * The `+0LL` trick is to make some old versions of gcc happy
 * when `a` is of a smaller type than `b`. Without this trick
 * the compiler would always throw a 'comparison is always
 * false' warning. Newer versions of gcc don't have that bug,
 * but `+0LL` is a no-op anyway, so it's here unconditionally.
 */
#define FRU_MAX(a, b) (((intmax_t)((a) + 0LL) > (intmax_t)((b) + 0LL)) ? (a) : (b)) 
#define FRU_MIN(a, b) (((intmax_t)((a) + 0LL) > (intmax_t)((b) + 0LL)) ? (b) : (a)) 
 
// BCD+ decoded data is twice the length of encoded,
// so is hex string for binary data
#define FRU_FIELDMAXARRAY     ((2 * FRU__FIELDMAXLEN) + 1)
 
/*
 * Public definitions
 */
 
#define FRU_INFO_AREAS 3 
#define FRU_FIRST_INFO_AREA FRU_CHASSIS_INFO 
#define FRU_LAST_INFO_AREA FRU_PRODUCT_INFO 
#define FRU_IS_INFO_AREA(atype) (FRU_FIRST_INFO_AREA <= (atype) \
                                 && (atype) <= FRU_LAST_INFO_AREA)
 
#define FRU_ATYPE_TO_INFOIDX(atype) (FRU_IS_INFO_AREA(atype) ? (int)((atype) - FRU_FIRST_INFO_AREA) : -1)
 
#define FRU_INFOIDX_TO_ATYPE(idx) (((idx) >= 0 && (idx) < FRU_INFO_AREAS) \
                                   ? (fru_area_type_t)((idx) + FRU_FIRST_INFO_AREA) \
                                   : (fru_area_type_t)(-1))
 
#define FRU_INFOIDX(a) FRU_ATYPE_TO_INFOIDX(FRU_##a##_INFO)
 
#define FRU_FOREACH_INFOIDX(it) for ((it) = 0; (it) <= FRU_INFO_AREAS; (it)++)
 
#define FRU_FOREACH_INFOFIELD(fru, atype, f, idx) \
    for (size_t idx = FRU_LIST_HEAD; \
         (f = fru_getfield(fru, atype, idx)); \
         idx++)
 
#define FRU_FOREACH_INFOCUSTOM(fru, atype, f, idx) \
    for (size_t idx = FRU_LIST_HEAD; \
         (f = fru_get_custom(fru, atype, idx)); \
         idx++)
 
typedef enum {
    FRU_FE_EMPTY, 
    FRU_FE_BASE, 
    FRU_FE_BINARY = (FRU__TYPE_BINARY + FRU_FE_BASE), 
    FRU_FE_MIN = FRU_FE_BINARY, 
    FRU_FE_BCDPLUS = (FRU__TYPE_BCDPLUS + FRU_FE_BASE), 
    FRU_FE_6BITASCII = (FRU__TYPE_ASCII_6BIT + FRU_FE_BASE), 
    FRU_FE_TEXT = (FRU__TYPE_TEXT + FRU_FE_BASE), 
    FRU_FE_MAX = FRU_FE_TEXT, 
    FRU_FE_AUTO, 
    FRU_FE_UNKNOWN, 
    FRU_FE_PRESERVE = FRU_FE_UNKNOWN, 
    FRU_FE_TOTALCOUNT, 
    FRU_FE_REALCOUNT = (FRU_FE_MAX - FRU_FE_MIN + 1), 
} fru_field_enc_t;
 
#define FRU_REAL_FE(t) ((t) - FRU_FE_BASE)
 
#define FRU_FE_FROMREAL(t) ((t) + FRU_FE_BASE)
 
#define FRU_FE_IS_REAL(t) (FRU_FE_MIN <= (t) && (t) <= FRU_FE_MAX)
 
#define FRU_FIELD_IS_REAL_ENC(f) ((f) && FRU_FE_IS_REAL((f)->enc))
 
#define FRU_FIELD_IS_AUTO_ENC(f) ((f) && FRU_FE_AUTO == ((f)->enc))
 
typedef struct {
    fru_field_enc_t enc; 
    char val[FRU_FIELDMAXARRAY]; 
} fru_field_t;
 
typedef void * fru_custom_t; // The actual type is not for public use
 
typedef struct {
    uint8_t type; 
    fru_field_t pn; 
    fru_field_t serial; 
    fru_custom_t cust; 
} fru_chassis_t;
 
typedef enum {
    FRU_CHASSIS_PARTNO,
    FRU_CHASSIS_SERIAL,
    FRU_CHASSIS_FIELD_COUNT
} fru_chassis_field_t;
typedef enum {
    FRU_LANG_DEFAULT = 0,  
    FRU_LANG_ENGLISH = 25, 
} fru_lang_t;
 
typedef struct {
    fru_lang_t lang; 
    struct timeval tv; 
    bool tv_auto; 
    fru_field_t mfg; 
    fru_field_t pname; 
    fru_field_t serial; 
    fru_field_t pn; 
    fru_field_t file; 
    fru_custom_t cust; 
} fru_board_t;
 
typedef enum {
    FRU_BOARD_MFG,
    FRU_BOARD_PRODNAME,
    FRU_BOARD_SERIAL,
    FRU_BOARD_PARTNO,
    FRU_BOARD_FILE,
    FRU_BOARD_FIELD_COUNT
} fru_board_field_t;
 
typedef struct {
    fru_lang_t lang;
    fru_field_t mfg; 
    fru_field_t pname; 
    fru_field_t pn; 
    fru_field_t ver; 
    fru_field_t serial; 
    fru_field_t atag; 
    fru_field_t file; 
    fru_custom_t cust; 
} fru_product_t;
 
typedef enum {
    FRU_PROD_MFG,
    FRU_PROD_NAME,
    FRU_PROD_MODELPN,
    FRU_PROD_VERSION,
    FRU_PROD_SERIAL,
    FRU_PROD_ASSET,
    FRU_PROD_FILE,
    FRU_PROD_FIELD_COUNT
} fru_prod_field_t;
 
#define FRU_MAX_FIELD_COUNT FRU_PROD_FIELD_COUNT
 
typedef void * fru_mr_t; // The actual type is not for public use
 
 
typedef enum {
    FRU_INTERNAL_USE, 
    FRU_MIN_AREA = FRU_INTERNAL_USE, 
    FRU_CHASSIS_INFO, 
    FRU_BOARD_INFO, 
    FRU_PRODUCT_INFO, 
    FRU_MR, 
    FRU_MAX_AREA = FRU_MR, 
    FRU_TOTAL_AREAS 
} fru_area_type_t;
#define FRU_IS_VALID_AREA(atype) (FRU_MIN_AREA <= (atype) && (atype) <= FRU_MAX_AREA)
 
#define FRU_FOREACH_AREA(it) for ((it) = FRU_MIN_AREA; (it) <= FRU_MAX_AREA; (it)++)
 
typedef struct {
    bool present[FRU_TOTAL_AREAS]; 
    fru_area_type_t order[FRU_TOTAL_AREAS]; 
    char * internal; 
    fru_chassis_t chassis; 
    fru_board_t board; 
    fru_product_t product; 
    fru_mr_t mr; 
} fru_t;
 
#define FRU_ATYPE_HAS_TYPE(atype) (FRU_CHASSIS_INFO == (atype))
#define FRU_ATYPE_HAS_LANG(atype) (FRU_BOARD_INFO == (atype) || FRU_PRODUCT_INFO == (atype))
 
typedef enum {
    FRU_NOFLAGS = 0, 
    FRU_IGNFVER = FRU__BIT(0), 
    FRU_IGNFHCKSUM = FRU__BIT(1), 
    FRU_IGNFDCKSUM = FRU__BIT(2), 
    FRU_IGNAVER = FRU__BIT(3), 
    FRU_IGNRVER = FRU__BIT(4), 
    FRU_IGNACKSUM = FRU__BIT(5), 
    FRU_IGNRHCKSUM = FRU__BIT(6), 
    FRU_IGNRDCKSUM = FRU__BIT(7), 
    FRU_IGNRNOEOL = FRU__BIT(8), 
    FRU_IGNBIG = FRU__BIT(9), 
    FRU_IGNAEOF = FRU__BIT(10), 
    FRU_IGNMRVER = FRU__BIT(11), 
    FRU_IGNMRDATALEN = FRU__BIT(12), 
} fru_flags_t;
bool fru_setfield(fru_field_t * field,
                  fru_field_enc_t encoding,
                  const char * string);
 
bool fru_setfield_binary(fru_field_t * field,
                         const void * buf,
                         size_t size);
 
fru_field_t * fru_getfield(const fru_t * fru,
                           fru_area_type_t atype,
                           size_t index);
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);
 
fru_field_t * fru_get_custom(const fru_t * fru,
                             fru_area_type_t atype,
                             size_t index);
 
bool fru_delete_custom(fru_t * fru,
                       fru_area_type_t atype,
                       size_t index);
 
#define FRU_ARRAY_SZ(a) (sizeof(a) / sizeof((a)[0]))
 
int16_t fru_hex2byte(const char * hex);
 
#define FRU_LIST_HEAD 0
#define FRU_LIST_TAIL INT_MAX
 
 
typedef enum {
    FRU_APOS_LAST = -3, 
    FRU_APOS_FIRST = -2, 
    FRU_APOS_AUTO = -1, 
    FRU_AFTER_INTERNAL, 
    FRU_APOS_MIN = FRU_AFTER_INTERNAL, 
    FRU_AFTER_CHASSIS, 
    FRU_AFTER_BOARD, 
    FRU_AFTER_PRODUCT, 
    FRU_AFTER_MR, 
    FRU_APOS_MAX = FRU_AFTER_MR, 
} fru_area_position_t;
#define FRU_IS_APOS_VALID(pos) (FRU_APOS_LAST <= (pos) && (pos) <= FRU_APOS_MAX)
 
 
fru_t * fru_init(fru_t * fru);
 
fru_t * fru_loadfile(fru_t * fru,
                     const char * filename,
                     fru_flags_t flags);
 
fru_t * fru_loadbuffer(fru_t * fru,
                       const void * buf,
                       size_t size,
                       fru_flags_t flags);
 
 
void fru_wipe(fru_t * fru);
 
#define fru_free(fru) do { fru_wipe(fru); fru__zfree(fru); } while(0)
 
bool fru_enable_area(fru_t * fru,
                     fru_area_type_t area,
                     fru_area_position_t after);
 
bool fru_disable_area(fru_t * fru, fru_area_type_t atype);
 
bool fru_move_area(fru_t * fru,
                   fru_area_type_t area,
                   fru_area_position_t after);
 
bool fru_savebuffer(void ** bufptr, size_t * size, const fru_t * fru);
 
bool fru_savefile(const char * fname, const fru_t * fru);
 
typedef enum {
    FRU_MR_MIN = 0x00, 
    FRU_MR_PSU_INFO = 0x00, 
    FRU_MR_DC_OUT = 0x01, 
    FRU_MR_DC_LOAD = 0x02, 
    FRU_MR_MGMT_ACCESS = 0x03, 
    FRU_MR_BCR = 0x04, 
    FRU_MR_ECR = 0x05, 
    FRU_MR_ASF_FIXED_SMBUS = 0x06, 
    FRU_MR_ASF_LEGACY_ALERTS = 0x07, 
    FRU_MR_ASF_REMOTE_CTRL = 0x08, 
    FRU_MR_EXT_DC_OUT = 0x09, 
    FRU_MR_EXT_DC_LOAD = 0x0A, 
    FRU_MR_NVME = 0x0B, 
    FRU_MR_NVME_PCIE_PORT = 0x0C, 
    FRU_MR_NVME_TOPOLOGY = 0x0D, 
    FRU_MR_NVME_RSVD_E = 0x0E, 
    FRU_MR_NVME_RSVD_F = 0x0F, 
    FRU_MR_OEM_START = 0xC0, 
    FRU_MR_OEM_END = 0xFF, 
    FRU_MR_MAX = FRU_MR_OEM_END, 
    FRU_MR_RAW, 
    FRU_MR_TYPE_COUNT, 
    FRU_MR_ANY, 
    FRU_MR_EMPTY, 
} fru_mr_type_t;
 
#define FRU_MR_IS_VALID_TYPE(t) (FRU_MR_MIN <= (t) && (t) <= FRU_MR_MAX)
 
#define FRU_MR_OEM_COUNT (FRU_MR_OEM_END - FRU_MR_OEM_START + 1)
 
#define FRU_MR_OEM(n) (FRU_MR_OEM_START + (n))
 
#define FRU__FILE_MRR_MAXDATA (UINT8_MAX) 
#define FRU__FILE_MRR_OEM_MFGID_LEN 3
/*
 * Encoded data must not exceed maximum possible MR record
 * data size. That's why we subtract the MFG ID length.
 */
#define FRU_MRR_OEM_MAXDATA \
    ((FRU__FILE_MRR_MAXDATA - FRU__FILE_MRR_OEM_MFGID_LEN) * 2 + 1)
 
#define FRU_MRR_RAW_MAXDATA \
    (FRU__FILE_MRR_MAXDATA * 2 + 1)
 
typedef enum {
    FRU_MR_MGMT_INVALID = 0x00, 
    FRU_MR_MGMT_MIN = 0x01, 
    FRU_MR_MGMT_SYS_URL = 0x01,  
    FRU_MR_MGMT_SYS_NAME = 0x02, 
    FRU_MR_MGMT_SYS_PING = 0x03, 
    FRU_MR_MGMT_COMPONENT_URL = 0x04,  
    FRU_MR_MGMT_COMPONENT_NAME = 0x05, 
    FRU_MR_MGMT_COMPONENT_PING = 0x06, 
    FRU_MR_MGMT_SYS_UUID = 0x07, 
    FRU_MR_MGMT_MAX = FRU_MR_MGMT_SYS_UUID, 
    FRU_MR_MGMT_INDEX_COUNT = FRU_MR_MGMT_MAX, 
} fru_mr_mgmt_type_t;
 
#define FRU_MR_MGMT_IS_SUBTYPE_VALID(mt) ((mt) >= FRU_MR_MGMT_MIN && (mt) <= FRU_MR_MGMT_MAX)
 
#define FRU_MR_MGMT_SUBTYPE_TO_IDX(mt) (FRU_MR_MGMT_IS_SUBTYPE_VALID(mt) \
                                        ? (int)((mt) - FRU_MR_MGMT_MIN) \
                                        : -1)
#define FRU_MR_MGMT_IDX_TO_SUBTYPE(i)  (((i) >= 0 && (i) <= FRU_MR_MGMT_MAX) \
                                        ? ((i) + FRU_MR_MGMT_MIN) \
                                        : FRU_MR_MGMT_INVALID)
 
typedef enum {
    FRU_NVME_FF_UNKNOWN = 0,
} fru_nvme_ff_t;
 
#define FRU__FILE_MR_MGMT_HDR_LEN (sizeof(uint8_t))
 
#define FRU__FILE_MR_MGMT_MAXDATA \
    (FRU__FILE_MRR_MAXDATA - FRU__FILE_MR_MGMT_HDR_LEN)
 
/*
 * All management subtype records are plain text strings,
 * and even UUID, which is binary, in decoded form is
 * represented as a sting of 32 hex digits, which is at
 * least twice less than the maximum length for any of the
 * plain text subtypes.
 *
 * Hence, encoded and decoded lengths for plain text strings
 * are the same, we just use the max encoded length here
 */
#define FRU_MR_MGMT_MAXDATA (FRU__FILE_MR_MGMT_MAXDATA)
 
typedef struct {
    fru_mr_type_t type; 
    union {
        struct {
        } psu;
        struct {
        } dco;
        struct {
        } edco;
        struct {
        } dcl;
        struct {
        } edcl;
        struct {
            fru_mr_mgmt_type_t subtype;
 
            char data[FRU_MR_MGMT_MAXDATA + 1]; /* 1 byte for terminator */
        } mgmt;
        struct {
        } bcr;
        struct {
        } ecr;
        struct {
            union {
                struct {
                } smbus;
                struct {
                } legacy;
                struct {
                } rc;
            };
        } asf;
 
        struct {
            union {
                struct {
                    fru_nvme_ff_t formfactor; 
                    uint8_t p1v8_init;
                    uint8_t p1v8_max;
                    uint8_t p3v3_init;
                    uint8_t p3v3_max;
                    uint8_t p3v3_aux_max;
                    uint8_t p5v_init;
                    uint8_t p5v_max;
                    uint8_t p12v_init;
                    uint8_t p12v_max;
                    uint8_t ptherm_max;
                    uint64_t capacity_lo; 
                    uint32_t capacity_mid; 
                    uint8_t capacity_hi; 
                } info;
                struct {
                } pcie;
                struct {
                } topology;
            };
        } nvme;
 
        struct {
            uint32_t mfg_id; 
            fru_field_enc_t enc; 
            char data[FRU_MRR_OEM_MAXDATA]; 
        } oem;
 
        struct {
            uint8_t type; 
            fru_field_enc_t enc; 
            char data[FRU_MRR_RAW_MAXDATA]; 
        } raw;
    };
} fru_mr_rec_t;
 
fru_mr_rec_t * fru_add_mr(fru_t * fru, size_t index, fru_mr_rec_t * rec);
 
fru_mr_rec_t * fru_get_mr(const fru_t * fru, size_t index);
 
fru_mr_rec_t * fru_find_mr(const fru_t * fru, fru_mr_type_t type, size_t * index);
 
bool fru_replace_mr(fru_t * fru, size_t index, fru_mr_rec_t * rec);
 
bool fru_delete_mr(fru_t * fru, size_t index);
 
bool fru_set_internal_binary(fru_t * fru, const void * buffer, size_t size);
 
bool fru_set_internal_hexstring(fru_t * fru, const void * hexstr);
 
bool fru_delete_internal(fru_t * fru);