we need to discuss the introduction and use of generic return values. they are mainly needed for libflashrom's public function, but could (and should) also be used internally whenever it is useful.
apart from naming (i.e. different ideas for prefixes. i'll use FL_ below but do not endorse this version more than others) it is very important to agree on the different error cases we want to define explicitly.
0 == FL_OK (no error) is pretty clear, but then the problems start already: should we report a warning as 0 or an error value? if the latter should it be a value of its own (e.g. FL_WARN) or should the different causes of warnings have all their own numbers?
my idea would be this: define different warning codes (or just one generic one like below) and put them in the range between FL_OK and FL_ERR, so that it is still easy to ignore them (e.g. if (ret <= FL_ERR) applies to real errors only).
then i would like you to look at the current code (and/or http://flashrom.org/Libflashrom) and list useful return values. we are (probably) not limited in the number of return values _technically_, but there should be a use case for more than just one function i.e. it should be somewhat generic and reusable. i'll start with a few very generic examples which i think might be useful and some which i have already used in my ICH descriptor patch:
* FL_ERR: generic/unspecified error. the function could not complete its job. the consequences should be at least defined in the documentation, a to-be-later-discussed errno value might have been set. the caller should abort whatever it is trying to do and inform the user.
* FL_WARN: similar to the above, but the function completed its job. there might have been some problems like untested devices or code that might lead to severe consequences later, but till return everything works as designed. an example for this could be that an init function is not able to unlock the whole address range. this is a problem and the user should be notified, but it is inside the scope of our error model and might not be a problem at all if the user does not want to access that region anyway. an example of something that clearly requires FL_ERR instead of FL_WARN would be if an init function of an external programmer can not detect the hardware. there is no easily distinguishable border between the two levels, but i think it will be clear from the context of the function what cases should be reported as errors and warnings respectively.
* FL_PARAM: a parameter is not in the expected range. this is actually somewhat of a favor to the calling function, because this means it has disregarded a precondition. we are returning this instead of showing undefined behavior.
* FL_OOB: (i.e. out of bounds) we had to abort because else we would reach across the bounds of a data structure (e.g. array).
* FL_OOM: (i.e. out of memory) one of malloc et al. failed. this is probably not very useful for the caller, but it can easily be distinguished by the callee and so there is no reason to not give it its own code imho.