From mboxrd@z Thu Jan 1 00:00:00 1970 Received: from eggs.gnu.org ([2001:4830:134:3::10]:55450) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1aK4pQ-0003JS-JF for qemu-devel@nongnu.org; Fri, 15 Jan 2016 08:54:13 -0500 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1aK4pN-0001No-Cq for qemu-devel@nongnu.org; Fri, 15 Jan 2016 08:54:12 -0500 Received: from roura.ac.upc.es ([147.83.33.10]:59104) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1aK4pN-0001Nf-0X for qemu-devel@nongnu.org; Fri, 15 Jan 2016 08:54:09 -0500 From: =?utf-8?b?TGx1w61z?= Vilanova Date: Fri, 15 Jan 2016 14:54:07 +0100 Message-Id: <145286604762.29455.8630766735054984295.stgit@localhost> In-Reply-To: <145286604004.29455.1509463776346981362.stgit@localhost> References: <145286604004.29455.1509463776346981362.stgit@localhost> MIME-Version: 1.0 Content-Type: text/plain; charset="utf-8" Content-Transfer-Encoding: quoted-printable Subject: [Qemu-devel] [PATCH v3 ] doc: Introduce coding style for errors List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , To: qemu-devel@nongnu.org Cc: Stefan Hajnoczi , Thomas Huth , "Dr . David Alan Gilbert" , Markus Armbruster Gives some general guidelines for reporting errors in QEMU. Signed-off-by: Llu=C3=ADs Vilanova --- 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 e= rrors +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 r= eference +a location on the offending input. + +7.2. Other errors + +QEMU provides the functions in "include/qapi/error.h" to report other ty= pes of +errors (i.e., not triggered by command line arguments or configuration f= iles). + +Functions in this header are used to accumulate error messages in an 'Er= ror' +object, which can be propagated up the call chain where it is finally re= ported. + +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 functio= ns and +special arguments. Specially, see 'error_fatal' and 'error_abort' to sho= w 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 gue= st code +translation or device code). Otherwise that can be abused by guest code = to +terminate QEMU. Instead, you should use the 'error_report()' routine.