[Qemu-devel] [PATCH v3 ] doc: Introduce coding style for errors

["Lluís Vilanova" <vilanova@ac.upc.edu>]

Gives some general guidelines for reporting errors in QEMU.

Signed-off-by: Lluís Vilanova <vilanova@ac.upc.edu>
---
 HACKING |   36 ++++++++++++++++++++++++++++++++++++
 1 file changed, 36 insertions(+)

diff --git a/HACKING b/HACKING
index 12fbc8a..1523bad 100644
--- a/HACKING
+++ b/HACKING
@@ -157,3 +157,39 @@ 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_fatal, "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.
+
+WARNING: Do *not* use 'error_fatal' or 'error_abort' for errors that are (or can
+be) triggered by guest code (e.g., some unimplimented corner case in guest code
+translation or device code). Otherwise that can be abused by guest code to
+terminate QEMU. Instead, you should use the 'error_report()' routine.