From mboxrd@z Thu Jan 1 00:00:00 1970 Received: from eggs.gnu.org ([2001:4830:134:3::10]:43763) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1a0wCz-0002GK-QZ for qemu-devel@nongnu.org; Mon, 23 Nov 2015 13:51:26 -0500 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1a0wCw-0001qD-3G for qemu-devel@nongnu.org; Mon, 23 Nov 2015 13:51:25 -0500 Received: from mx1.redhat.com ([209.132.183.28]:55030) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1a0wCv-0001q9-S6 for qemu-devel@nongnu.org; Mon, 23 Nov 2015 13:51:22 -0500 Date: Mon, 23 Nov 2015 18:51:16 +0000 From: "Daniel P. Berrange" Message-ID: <20151123185116.GV18085@redhat.com> References: <144830407261.1693.6845199723252391860.stgit@localhost> <144830408403.1693.5595372859320618258.stgit@localhost> MIME-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Disposition: inline In-Reply-To: <144830408403.1693.5595372859320618258.stgit@localhost> Content-Transfer-Encoding: quoted-printable Subject: Re: [Qemu-devel] [PATCH v2 2/2] doc: Introduce coding style for errors Reply-To: "Daniel P. Berrange" List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , To: =?utf-8?B?TGx1w61z?= Vilanova Cc: Stefan Hajnoczi , Thomas Huth , qemu-devel@nongnu.org, Markus Armbruster , "Dr . David Alan Gilbert" On Mon, Nov 23, 2015 at 07:41:24PM +0100, Llu=C3=ADs Vilanova wrote: > Gives some general guidelines for reporting errors in QEMU. >=20 > Signed-off-by: Llu=C3=ADs Vilanova > --- > HACKING | 31 +++++++++++++++++++++++++++++++ > 1 file changed, 31 insertions(+) >=20 > diff --git a/HACKING b/HACKING > index 12fbc8a..e59bc34 100644 > --- a/HACKING > +++ b/HACKING > @@ -157,3 +157,34 @@ 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 shoul= d use one > +of these mechanisms instead of manually reporting them (i.e., do not u= se > +'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 o= r > +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_warn, "Error with %s", "arguments"); > + > +See the "include/qapi/error.h" header for additional convenience funct= ions and > +special arguments. Specially, see 'error_fatal' and 'error_abort' to s= how errors > +and immediately terminate QEMU. I don't think this "Errors in user inputs" vs "Other errors" distinction really makes sense. Whether an error raised in a piece of code is related to user input or not is almost impossible to determine in practice. So as a rule to follow it is not practical. AFAIK, include/qemu/error-report.h is the historical failed experiment in structured error reporting, while include/qapi/error.h is the new preferred error reporting system that everything should be using. On this basis, I'd simply say that include/qemu/error-report.h is legacy code that should no longer be used, and that new code should use include/qapi/error.h exclusively and existing code converted where practical. Regards, Daniel --=20 |: http://berrange.com -o- http://www.flickr.com/photos/dberrange= / :| |: http://libvirt.org -o- http://virt-manager.or= g :| |: http://autobuild.org -o- http://search.cpan.org/~danberr= / :| |: http://entangle-photo.org -o- http://live.gnome.org/gtk-vn= c :|