- Generated by
1.9.8
|
libfru 3.0.2.gb79b203
FRU Manupulation Library
|
This work is dual-licensed under Apache 2.0 and GPL 2.0 (or any later version) for the frugen utility, or under Apache 2.0 and Lesser GPL 2.0 (or any later version) for the fru library.
You can choose between one of them if you use this work.
SPDX-License-Identifier: Apache-2.0 OR GPL-2.0-or-later
This project was incepted to eventually create a universal, full-featured IPMI FRU Information generator / editor library and command line tool, written in full compliance with IPMI FRU Information Storage Definition v1.0, rev. 1.3.
This is the library behind frugen. It is aimed at providing a very easy-to-use API that completely (well, almost) abstracts the user from the details of the binary FRU file internals. All data that the user has to deal with is either plain text or hex strings (in rare occasions raw binary data buffers may also be supported).
Most memory management in the library is automatic and the users don't have to care about freeing any internal allocations as long as they use the library API properly. The central entity of the library is fru_t, the structure type that represents a fully decoded FRU information as a whole. You will find fields for every FRU area inside that structure, and there is a lot of functions to work with that structure. You may load it from a file or from an in-memory buffer, and you may save it back. In the meantime you're free to modify the data in the structure as you want.
The main idea is that all the data in fru_t is in text, human-readable format, except for integer fields like, for instance, fru_t.chassis.type. The API however has functions to set the values from binary buffers. Those include fru_setfield_binary() and fru_set_internal_binary().
Any errors detected by the API calls they will report via a familiar POSIX-like mechanism of a global thread-specific fru_errno variable, which in libfru is enhanced to provide the caller with the information on where exactly the error has occured.
Please read the doxygen-formatted documentation thoroughly before first use. You may also check frugen.c and frugen-json.c code for library usage examples.
So far supported in libfru are:
NOT supported:
The frugen tool supports the following (limitations imposed by the libfru library):
NOTE: You may use frugen to modify some standard fields even on FRU files that contain unsupported multirecord area records. Those records will be decoded as 'custom' (raw) type and encoded back the same way, preserving their data.
NOTE: You may use frugen to fix area and record checksums in your FRU file. For that purpose use binary input and output formats, and specify the debug (-g) flags to ingnore the errors in your source FRU file. The checksums for the destination FRU file will be recalculated properly according to the specification. Please note that FRU files with bad header checksum will not be processed as there is no debug flag to ignore that error.
The frugen tool takes a template in any of the supported formats and builds an 'exploded' or 'decoded' version of fru file in memory. It then takes command line arguments and applies any changes to the fru fields specified by those arguments. After that step is complete, it either encodes/packs the data into a binary fru file, or dumps it in json or plain text format to a file or stdout.
Any text field in FRU has an encoding type. The IPMI FRU specification defines 4 types: Text (ASCII), 6-bit ASCII, BCD+, and binary. The tool can detect which encoding suits best for the provided data or it can preserve the original encoding used in the source template.
If autodetection is chosen (see the 'set' option below), then the tool will attempt to encode the new data the most compact/efficient way. It will start with 6-bit ASCII encoding as it yields the most compact result. If your data string contains anything beyond uppercase ASCII, digits, and punctuation, the tool will expand the charset and attempt to use BCD+. If that doesn't fit, a binary encoding will be attempted. If there is anything beyond hex digits, then finally the data string will be copied as is (plain text encoding).
NOTE: Previous versions of frugen would start with binary encoding, having the rest of the order the same.
If you choose to preserve the original encoding, please note that frugen will fail if your new data cannot be encoded using the same encoding type as the original. For instance, if your original data was "ACME" encoded as 6-bit ASCII, and you want to preserve the encoding, but the new data is "A Company
Making Everything", then the tool will fail because 6-bit encoding doesn't allow for lowercase characters.
Input binary FRU files (or templates as considered by frugen) may contain multirecord areas. Such areas consist of many so-called 'records' of various types, including some OEM ones that aren't covered by IPMI FRU specification. It is impossible for frugen or libfru to support them all, but the best effort is made to not destroy them at least. When using a binary FRU file as a template, frugen will load such records as raw type (see fru_mr_rec_t::raw), and will save them into json output as 'custom'
A similar approach is used for the iternal use area, the contents of which are completely OEM-specific and can not be parsed. The are is decoded as a hex string and then encoded back into a raw binary.
For the most up-to-date information on the frugen tool invocation and options, please use frugen -h, below is an example of the output of that command:
Dependency: json-c library
The frugen tool supports JSON files. You may specify all the FRU info fields (mind the general tool limitations) in a file and use it as an input for the tool:
frugen --json example.json fru.bin
An example file 'example.json' is provided for your reference.
NOTE: The JSON file for frugen is allowed to have C-style comments (/* comment */), which is an extension to the standard JSON format.
mkdir build && cd build cmake .. make
There is a number of optional parameters for cmake to control build procedure:
| Option | Default | Description |
|---|---|---|
| BINARY_32BIT | OFF | Build 32-bit versions of everything |
| BUILD_SHARED_LIB | ON | Build libfru as a shared library, implies dynamic linking of frugen |
| BINARY_STATIC | OFF | Force full static linking of frugen, makes it HUGE |
| ENABLE_JSON | ON | Enable JSON support if json-c library is available |
| JSON_STATIC | OFF | Link json-c library statically into frugen |
NOTE: BUILD_SHARED_LIB and BINARY_STATIC are not mutually exclusive: while first option controls building libfru, second one is related to frugen. When both options are enabled static and shared versions of libfru will be compiled. When both options are disabled libfru will be linked statically into frugen, while other libraries are linked shared.
To build a debug version use the following command:
mkdir build && cd build cmake -DCMAKE_BUILD_TYPE=Debug -DDEBUG_OUTPUT=yes .. make
To build a semi-statically linked version (with libfru and libjson-c built-in), use:
mkdir build && cd build cmake -DBINARY_STATIC=ON -DJSON_STATIC=ON .. make
To build project documentation (requies doxygen), run make docs.
You will need a MingW32 toolchain. This chapter is written in assumption you're using x86_64-w64-mingw32.
First of all you will need to create a x86_64-w64-mingw32-toolchain.cmake file describing your cross-compilation toolchain.
This file assumes that you use $HOME/mingw-install as an installation prefix for all mingw32-compiled libraries (e.g., libjson-c).
# the name of the target operating system
SET(CMAKE_SYSTEM_NAME Windows)
SET(MINGW32_INSTALL_DIR $ENV{HOME}/mingw-install)
# which compilers to use for C and C++
SET(CMAKE_C_COMPILER x86_64-w64-mingw32-gcc)
SET(CMAKE_CXX_COMPILER x86_64-w64-mingw32-g++)
SET(CMAKE_RC_COMPILER x86_64-w64-mingw32-windres)
# here is the target environment located
SET(CMAKE_FIND_ROOT_PATH /usr/x86_64-w64-mingw32/ ${MINGW32_INSTALL_DIR})
# adjust the default behaviour of the FIND_XXX() commands:
# search headers and libraries in the target environment, search
# programs in the host environment
set(CMAKE_FIND_ROOT_PATH_MODE_PROGRAM NEVER)
set(CMAKE_FIND_ROOT_PATH_MODE_LIBRARY ONLY)
set(CMAKE_FIND_ROOT_PATH_MODE_INCLUDE ONLY)
# let the compiler find the includes and linker find the libraries
# MinGW linker doesn't accept absolute library paths found
# by find_library()
include_directories(BEFORE ${MINGW32_INSTALL_DIR}/include)
set(CMAKE_LIBRARY_PATH ${MINGW32_INSTALL_DIR}/lib ${MINGW32_INSTALL_DIR}/usr/lib ${CMAKE_LIBRARY_PATH})
Once you have that file, build the tool as follows:
cmake -DCMAKE_TOOLCHAIN_FILE=x86_64-w64-mingw32-toolchain.cmake . make
Should you have any questions or proposals, please feel free to:
1.9.8