From patchwork Tue Feb 9 13:25:58 2016 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-Patchwork-Submitter: Markus Armbruster X-Patchwork-Id: 8261911 Return-Path: X-Original-To: patchwork-qemu-devel@patchwork.kernel.org Delivered-To: patchwork-parsemail@patchwork1.web.kernel.org Received: from mail.kernel.org (mail.kernel.org [198.145.29.136]) by patchwork1.web.kernel.org (Postfix) with ESMTP id 9C9AE9F38B for ; Tue, 9 Feb 2016 13:26:30 +0000 (UTC) Received: from mail.kernel.org (localhost [127.0.0.1]) by mail.kernel.org (Postfix) with ESMTP id EA14320260 for ; Tue, 9 Feb 2016 13:26:29 +0000 (UTC) Received: from lists.gnu.org (lists.gnu.org [208.118.235.17]) (using TLSv1 with cipher AES256-SHA (256/256 bits)) (No client certificate requested) by mail.kernel.org (Postfix) with ESMTPS id 2762E20268 for ; Tue, 9 Feb 2016 13:26:28 +0000 (UTC) Received: from localhost ([::1]:55997 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1aT8JH-0002Gy-Ey for patchwork-qemu-devel@patchwork.kernel.org; Tue, 09 Feb 2016 08:26:27 -0500 Received: from eggs.gnu.org ([2001:4830:134:3::10]:39929) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1aT8Iw-00029I-Vs for qemu-devel@nongnu.org; Tue, 09 Feb 2016 08:26:11 -0500 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1aT8Is-0005kw-UC for qemu-devel@nongnu.org; Tue, 09 Feb 2016 08:26:06 -0500 Received: from mx1.redhat.com ([209.132.183.28]:49918) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1aT8Is-0005kq-My for qemu-devel@nongnu.org; Tue, 09 Feb 2016 08:26:02 -0500 Received: from int-mx09.intmail.prod.int.phx2.redhat.com (int-mx09.intmail.prod.int.phx2.redhat.com [10.5.11.22]) by mx1.redhat.com (Postfix) with ESMTPS id 653235A70 for ; Tue, 9 Feb 2016 13:26:02 +0000 (UTC) Received: from blackfin.pond.sub.org (ovpn-116-34.ams2.redhat.com [10.36.116.34]) by int-mx09.intmail.prod.int.phx2.redhat.com (8.14.4/8.14.4) with ESMTP id u19DQ0Mh002992 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-GCM-SHA384 bits=256 verify=NO) for ; Tue, 9 Feb 2016 08:26:01 -0500 Received: by blackfin.pond.sub.org (Postfix, from userid 1000) id 1C28B3006AEB; Tue, 9 Feb 2016 14:25:59 +0100 (CET) From: Markus Armbruster To: qemu-devel@nongnu.org Date: Tue, 9 Feb 2016 14:25:58 +0100 Message-Id: <1455024358-31133-4-git-send-email-armbru@redhat.com> In-Reply-To: <1455024358-31133-1-git-send-email-armbru@redhat.com> References: <1455024358-31133-1-git-send-email-armbru@redhat.com> MIME-Version: 1.0 X-Scanned-By: MIMEDefang 2.68 on 10.5.11.22 X-detected-operating-system: by eggs.gnu.org: GNU/Linux 3.x X-Received-From: 209.132.183.28 Subject: [Qemu-devel] [PULL 3/3] HACKING: Add a section on error handling and reporting X-BeenThere: qemu-devel@nongnu.org X-Mailman-Version: 2.1.14 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: qemu-devel-bounces+patchwork-qemu-devel=patchwork.kernel.org@nongnu.org Sender: qemu-devel-bounces+patchwork-qemu-devel=patchwork.kernel.org@nongnu.org X-Spam-Status: No, score=-6.9 required=5.0 tests=BAYES_00, RCVD_IN_DNSWL_HI, UNPARSEABLE_RELAY autolearn=unavailable version=3.3.1 X-Spam-Checker-Version: SpamAssassin 3.3.1 (2010-03-16) on mail.kernel.org X-Virus-Scanned: ClamAV using ClamSMTP Inspired by an RFC PATCH from Lluís Vilanova. Signed-off-by: Markus Armbruster Message-Id: <1454522628-28294-3-git-send-email-armbru@redhat.com> Reviewed-by: Lluís Vilanova --- HACKING | 55 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 55 insertions(+) diff --git a/HACKING b/HACKING index 12fbc8a..058aa8f 100644 --- a/HACKING +++ b/HACKING @@ -157,3 +157,58 @@ 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 handling and reporting + +7.1 Reporting errors to the human user + +Do not use printf(), fprintf() or monitor_printf(). Instead, use +error_report() or error_vreport() from error-report.h. This ensures the +error is reported in the right place (current monitor or stderr), and in +a uniform format. + +Use error_printf() & friends to print additional information. + +error_report() prints the current location. In certain common cases +like command line parsing, the current location is tracked +automatically. To manipulate it manually, use the loc_*() from +error-report.h. + +7.2 Propagating errors + +An error can't always be reported to the user right where it's detected, +but often needs to be propagated up the call chain to a place that can +handle it. This can be done in various ways. + +The most flexible one is Error objects. See error.h for usage +information. + +Use the simplest suitable method to communicate success / failure to +callers. Stick to common methods: non-negative on success / -1 on +error, non-negative / -errno, non-null / null, or Error objects. + +Example: when a function returns a non-null pointer on success, and it +can fail only in one way (as far as the caller is concerned), returning +null on failure is just fine, and certainly simpler and a lot easier on +the eyes than propagating an Error object through an Error ** parameter. + +Example: when a function's callers need to report details on failure +only the function really knows, use Error **, and set suitable errors. + +Do not report an error to the user when you're also returning an error +for somebody else to handle. Leave the reporting to the place that +consumes the error returned. + +7.3 Handling errors + +Calling exit() is fine when handling configuration errors during +startup. It's problematic during normal operation. In particular, +monitor commands should never exit(). + +Do not call exit() or abort() to handle an error that can be triggered +by the guest (e.g., some unimplemented corner case in guest code +translation or device emulation). Guests should not be able to +terminate QEMU. + +Note that &error_fatal is just another way to exit(1), and &error_abort +is just another way to abort().