Icon: "nico.h@gmx.de: Rename flashrom -> flashprog"

2023-12-03T17:46:43Z

"nico.h@gmx.de: Rename flashrom -> flashprog"

New page

{{DISPLAYTITLE: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'''

<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 libflashprog patches existed. The text below needs to be revised to reflect the available libflashprog patches and the design below needs review.
</div>

== 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.

=== Layouts ===

=== 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 '''l'''ib'''f'''lashrom), 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.

Libflashprog - Revision history

Icon: "nico.h@gmx.de: Rename flashrom -> flashprog"