libflashprog

libflashprog 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 libflashprog.a

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

API

The following sections describe how a libflashprog 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 libflashprog.

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

fl_set_loglevel() Set the loglevel which libflashprog 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 libflashprog 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 libflashprog, 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 libflashprog 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 flashprog_layout;

flashprog_layout_read_from_ifd(layout, flashctx[, buf])

flashprog_layout_read_fmap_from_rom(layout, flashctx)

flashprog_layout_read_fmap_from_buffer(layout, flashctx, buf)

flashprog_layout_include_region(layout, name)

flashprog_layout_release(layout)

We need more flexibility:

enum flashprog_layout_type;

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

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

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

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

flashprog_layout_read(buf, len, datasrc)

flashprog_layout_release_region()

struct flashprog_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 = flashprog_datasrc_from_file("file.name");
 flash_datasrc = flashprog_datasrc_from_flashctx(flashctx);

 flashprog_layout_read(layout, FLASHPROG_LAYOUT_TYPE_FMAP, file_datasrc);
 flashprog_layout_region_from_layout(region_datasrc, layout, "region3", flash_datasrc);
 flashprog_layout_read(layout, FLASHPROG_LAYOUT_TYPE_CBFS, region_datasrc);

And fallback/ramstage from within:

 flashprog_layout_region_from_layout(ramstage_datasrc, layout, "fallback/ramstage", region_datasrc);
 flashprog_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 libflashprog.

• There should be one single flashprog.h or libflashprog.h include file, which contains (only!) the function prototypes and macros which belong to the public libflashprog 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 libflashprog.
  • 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 libflashprog 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 libflashprog.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 libflashprog 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.