[v5,5/5] doc: Introduce coding style for errors

Commit Message

Lluís Vilanova Jan. 28, 2016, 9:53 p.m. UTC

Gives some general guidelines for reporting errors in QEMU.

Signed-off-by: Lluís Vilanova <[e-mail]>
---
 HACKING |   33 +++++++++++++++++++++++++++++++++
 1 file changed, 33 insertions(+)

Comments

Eric Blake Jan. 28, 2016, 10:01 p.m. UTC | #1

On 01/28/2016 02:53 PM, Lluís Vilanova wrote:
> Gives some general guidelines for reporting errors in QEMU.
> 
> Signed-off-by: Lluís Vilanova <[e-mail]>
> ---
>  HACKING |   33 +++++++++++++++++++++++++++++++++
>  1 file changed, 33 insertions(+)

I'm not sure if my v4 review crossed paths with this, but I still see typos:

> +
> +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/

Lluís Vilanova Jan. 29, 2016, 1:33 p.m. UTC | #2

Eric Blake writes:

> On 01/28/2016 02:53 PM, Lluís Vilanova wrote:
>> Gives some general guidelines for reporting errors in QEMU.
>> 
>> Signed-off-by: Lluís Vilanova <[e-mail]>
>> ---
>> HACKING |   33 +++++++++++++++++++++++++++++++++
>> 1 file changed, 33 insertions(+)

> I'm not sure if my v4 review crossed paths with this, but I still see typos:

>> +
>> +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/

We did cross paths, sorry. It's fixed on upcoming v6.

Lluis

Patch

diff --git a/HACKING b/HACKING
index 12fbc8a..aecc77c 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()').
+
+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 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.