[flashrom] Error Codes for libflashrom (and elsewhere)

[Stefan Tauner]

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.

-- 
Kind regards/Mit freundlichen Grüßen, Stefan Tauner