Nico@flashrom.org/ (talk) |
|
| Line 1: |
Line 1: |
| {{DISPLAYTITLE:libflashrom}}
| | [[Category:Deleted]] |
| '''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'''
| |
| | |
| <div style="margin-top:0.5em; padding:0.5em 0.5em 0.5em 0.5em; background-color:#ff6666; align:right; border:1px solid #000000;">
| |
| | |
| 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.
| |
| </div>
| |
| | |
| == 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.
| |
| | |
| === Layouts ===
| |
| | |
| === 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 '''l'''ib'''f'''lashrom), 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.
| |