libflashrom

libflashrom is a shared library which can be used to write programs which need to detect/read/write/erase flash ROM chips using various programmers.

It is, among other things, useful so that different frontends can be written (a command-line tool, various GUIs, libpayload integration, others).

Status

Work in progress.

Building

$ make libflashrom.a

Please note that some/all of the text below was written before libflashrom patches existed. The text below needs to be revised to reflect the available libflashrom patches and the design below needs review.

API

The following sections describe how a libflashrom API could look like. This is just a first attempt, it's not yet finished and not yet implemented. Comments welcome.

General

fl_init() Initialize libflashrom.

fl_shutdown() Shut down libflashrom, close devices or files, free all resources, etc.

fl_set_loglevel() Set the loglevel which libflashrom should use to output errors/warnings/info/debug messages. Valid loglevels: TODO.

fl_set_log_callback() Set a callback function which will be invoked whenever libflashrom wants to output messages. This allows frontends to do whatever they see fit with such messages, e.g. write them to syslog, or to file, or print them in a GUI window, etc.

Querying

fl_version() Return one or more version items of libflashrom, e.g. the lib major/minor/micro version number, the svn revision, or similar.

fl_sysinfo() Return some information about the (build- and host-) system, which libflashrom knows about, e.g. gcc version used, libpci version, uname, etc.

fl_supported_programmers() Get a list of supported programmers.

fl_supported_chips() Get a list of supported flash ROM chips.

fl_supported_boards() Get a list of supported mainboards.

fl_supported_chipsets() Get a list of supported chipsets.

Programmers

fl_programmer_init() Initialize the specified programmer.

fl_programmer_shutdown() Shut down the specified programmer.

fl_programmer_capabilities() Get the capabilities of the specified programmer. Valid capabilities: TODO.

Operations

fl_image_read() Read the current image from the specified ROM chip.

fl_image_write() Write the specified image to the specified ROM chip.

fl_image_erase() Erase the specified ROM chip.

fl_image_verify() Verify if the specified image is the same as the contents of the specified ROM chip.

What we have:

struct flashrom_layout;

flashrom_layout_read_from_ifd(layout, flashctx[, buf])

flashrom_layout_read_fmap_from_rom(layout, flashctx)

flashrom_layout_read_fmap_from_buffer(layout, flashctx, buf)

flashrom_layout_include_region(layout, name)

flashrom_layout_release(layout)

We need more flexibility:

enum flashrom_layout_type;

struct flashrom_datasrc; where the layout is read from, may include region infos

flashrom_layout_read(layout, layout_type, datasrc) searches for layout_type and adds entries to layout

flashrom_layout_region_from_layout(region_datasrc, layout, region_name, datasrc) creates region specific datasrc from layout info and original datasrc (maybe internal-only function)

flashrom_layout_region_from_path(region_datasrc, path, datasrc) path like ifd:bios/ifwi:lbp2/obb

flashrom_layout_read(buf, len, datasrc)

flashrom_layout_release_region()

struct flashrom_layout could be exported as JSON, e.g.:

 {
   "offset": 0,
   "length": 0x100000,
   "ifd": [
     "fd": {
       "offset": 0,
       "length": 0xfff
     },
     "gbe": {
       "offset": 0x1000,
       "length": 0x2000
     },
     "bios": {
       "offset": 0x3000,
       "length": 0xffd000,
       "fmap": [
         ...
       ]
     }
   ]
 }

Pseudocode example:

We want to read a primary layout from a file and CBFS layout from flash:

 file_datasrc = flashrom_datasrc_from_file("file.name");
 flash_datasrc = flashrom_datasrc_from_flashctx(flashctx);

 flashrom_layout_read(layout, FLASHROM_LAYOUT_TYPE_FMAP, file_datasrc);
 flashrom_layout_region_from_layout(region_datasrc, layout, "region3", flash_datasrc);
 flashrom_layout_read(layout, FLASHROM_LAYOUT_TYPE_CBFS, region_datasrc);

And fallback/ramstage from within:

 flashrom_layout_region_from_layout(ramstage_datasrc, layout, "fallback/ramstage", region_datasrc);
 flashrom_layout_read(ramstage_buf, length, ramstage_datasrc);

Other

...

TODO

This is a random list of TODO items which need to be fixed in order to make a usable and useful libflashrom.

• There should be one single flashrom.h or libflashrom.h include file, which contains (only!) the function prototypes and macros which belong to the public libflashrom API.
• All functions and macros of the public API should have a prefix in order to not pollute the namespace of the programs that link against libflashrom.
  • Suggestion: fl_ and FL_. Examples: fl_init() or FL_ERR_MALLOC.
  • Other ideas: lf_/LF_ (for libflashrom), or lfr_/LFR_ or rom_/ROM_ (though that's a bit too generic maybe).
• No function in libflashrom is allowed to call exit().
• All public API functions should return meaningful and unique error codes (which should have useful macros/names such as FL_OK, FL_ERR_MALLOC, etc.).
• pkg-config support would be nice, i.e., some simple libflashrom.pc file.
• It should be evaluated if it makes sense to use libtool (it probably does) to get a well-tested and portable shared library handling (only "manual" libtool, no autoconf/automake).
• The public API should not use C99 features, as that makes it hard or even impossible to use the lib from C++ code (e.g. via a Qt-based GUI) or to make a C++ wrapper lib. Specifically .name = "foo" syntax is problematic for example (in the public API, doesn't matter if used elsewhere).
• Making Python- or Ruby-bindings at some point is also interesting and feasible once libflashrom is sufficiently usable.
• The number of global variables should be reduced, in the best case they should all be eliminated. Those that might remain should get the prefix (see above) to avoid namespace conflicts.
• All fprintf()/printf() calls in the lib should be eliminated, only msg_*() function calls should be used.
• A progress indicator functionality should be provided for all operations, in order to allow GUIs to display a progressbar or similar.