Re: [Qemu-devel] [PATCH v2 2/2] doc: Introduce coding style for errors

[Daniel P. Berrange]

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 <address@hidden>
> ---
>  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 :|