Re: [Qemu-devel] [PATCH v4 5/5] doc: Introduce coding style for errors

[Eric Blake <eblake@redhat.com>]

[-- Attachment #1: Type: text/plain, Size: 2720 bytes --]

On 01/28/2016 02:41 PM, Lluís Vilanova wrote:
> Gives some general guidelines for reporting errors in QEMU.
> 
> Signed-off-by: Lluís Vilanova <vilanova@ac.upc.edu>
> ---
>  HACKING |   33 +++++++++++++++++++++++++++++++++
>  1 file changed, 33 insertions(+)
> 
> diff --git a/HACKING b/HACKING
> index 12fbc8a..f5783d4 100644
> --- a/HACKING
> +++ b/HACKING
> @@ -157,3 +157,36 @@ 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 various mechanisms for reporting errors using a uniform format,
> +ensuring the user will receive them (e.g., shown in QMP when necessary). You
> +should use one of these mechanisms instead of manually reporting them (i.e., do
> +not use 'printf()', 'exit()' or 'abort()').

abort() for unreachable code may be okay, but I'm not sure how to word
that.  Maybe "avoid use 'printf()' or 'exit()', and minimize use of
'abort()' situations that should be unreachable code".

May be worth mentioning that if the user can trigger it (command line,
hotplug, etc) then we want fatal; if it represents a programming bug
that the user should not be able to trigger, then abort is okay.

> +
> +7.1. Simple error messages
> +
> +The 'error_report*()' functions in "include/qemu/error-report.h" will
> +immediately report error messages to the user.
> +
> +WARNING: Do *not* use 'error_report_fatal()' or 'error_report_abort()' for
> +errors that are (or can be) triggered by guest code (e.g., some unimplimented

s/unimplimented/unimplemented/

> +corner case in guest code translation or device code). Otherwise that can be
> +abused by guest code to terminate QEMU. Instead, you should use
> +'error_report()'.
> +
> +7.2. Errors in user inputs
> +
> +The 'loc_*()' functions in "include/qemu/error-report.h" will extend the
> +messages from 'error_report*()' with references to locations in inputs provided
> +by the user (e.g., command line arguments or configuration files).
> +
> +7.3. More complex error management
> +
> +The functions in "include/qapi/error.h" can be used to accumulate error messages
> +in an 'Error' object, which can be propagated up the call chain where it is
> +finally reported.
> +
> +WARNING: The special 'error_fatal' and 'error_abort' objects follow the same
> +constrains as the 'error_report_fatal' and 'error_report_abort' functions.

s/constrains/constraints/

-- 
Eric Blake   eblake redhat com    +1-919-301-3266
Libvirt virtualization library http://libvirt.org


[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 604 bytes --]