On Mon, Nov 23, 2015 at 07:41:24PM +0100, Lluís Vilanova wrote: > Gives some general guidelines for reporting errors in QEMU. > > Signed-off-by: Lluís Vilanova <vilan...@ac.upc.edu> > --- > HACKING | 31 +++++++++++++++++++++++++++++++ > 1 file changed, 31 insertions(+) > > diff --git a/HACKING b/HACKING > index 12fbc8a..e59bc34 100644 > --- a/HACKING > +++ b/HACKING > @@ -157,3 +157,34 @@ painful. These are: > * you may assume that integers are 2s complement representation > * you may assume that right shift of a signed integer duplicates > the sign bit (ie it is an arithmetic shift, not a logical shift) > + > +7. Error reporting > + > +QEMU provides two different mechanisms for reporting errors. You should use > one > +of these mechanisms instead of manually reporting them (i.e., do not use > +'printf', 'exit' or 'abort'). > + > +7.1. Errors in user inputs > + > +QEMU provides the functions in "include/qemu/error-report.h" to report errors > +related to inputs provided by the user (e.g., command line arguments or > +configuration files). > + > +These functions generate error messages with a uniform format that can > reference > +a location on the offending input. > + > +7.2. Other errors > + > +QEMU provides the functions in "include/qapi/error.h" to report other types > of > +errors (i.e., not triggered by command line arguments or configuration > files). > + > +Functions in this header are used to accumulate error messages in an 'Error' > +object, which can be propagated up the call chain where it is finally > reported. > + > +In its simplest form, you can immediately report an error with: > + > + error_setg(&error_warn, "Error with %s", "arguments"); > + > +See the "include/qapi/error.h" header for additional convenience functions > and > +special arguments. Specially, see 'error_fatal' and 'error_abort' to show > errors > +and immediately terminate QEMU.
I don't think this "Errors in user inputs" vs "Other errors" distinction really makes sense. Whether an error raised in a piece of code is related to user input or not is almost impossible to determine in practice. So as a rule to follow it is not practical. AFAIK, include/qemu/error-report.h is the historical failed experiment in structured error reporting, while include/qapi/error.h is the new preferred error reporting system that everything should be using. On this basis, I'd simply say that include/qemu/error-report.h is legacy code that should no longer be used, and that new code should use include/qapi/error.h exclusively and existing code converted where practical. Regards, Daniel -- |: http://berrange.com -o- http://www.flickr.com/photos/dberrange/ :| |: http://libvirt.org -o- http://virt-manager.org :| |: http://autobuild.org -o- http://search.cpan.org/~danberr/ :| |: http://entangle-photo.org -o- http://live.gnome.org/gtk-vnc :|