From mboxrd@z Thu Jan 1 00:00:00 1970 Received: from eggs.gnu.org ([2001:4830:134:3::10]:48542) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1aOuSf-0003EQ-Mo for qemu-devel@nongnu.org; Thu, 28 Jan 2016 16:50:46 -0500 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1aOuSc-0003dV-Gf for qemu-devel@nongnu.org; Thu, 28 Jan 2016 16:50:41 -0500 Received: from mx1.redhat.com ([209.132.183.28]:49578) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1aOuSc-0003dH-8v for qemu-devel@nongnu.org; Thu, 28 Jan 2016 16:50:38 -0500 References: <145401727502.31479.11571397180565966513.stgit@localhost> <145401730295.31479.7043845714018218355.stgit@localhost> From: Eric Blake Message-ID: <56AA8D2C.5050403@redhat.com> Date: Thu, 28 Jan 2016 14:50:36 -0700 MIME-Version: 1.0 In-Reply-To: <145401730295.31479.7043845714018218355.stgit@localhost> Content-Type: multipart/signed; micalg=pgp-sha256; protocol="application/pgp-signature"; boundary="Vj3kB8CQRgLpOHp8LPgGjjhRaLSqdrhX4" Subject: Re: [Qemu-devel] [PATCH v4 5/5] doc: Introduce coding style for errors List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , To: =?UTF-8?Q?Llu=c3=ads_Vilanova?= , qemu-devel@nongnu.org Cc: Stefan Hajnoczi , Thomas Huth , "Dr . David Alan Gilbert" , Markus Armbruster This is an OpenPGP/MIME signed message (RFC 4880 and 3156) --Vj3kB8CQRgLpOHp8LPgGjjhRaLSqdrhX4 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: quoted-printable On 01/28/2016 02:41 PM, Llu=C3=ADs Vilanova wrote: > Gives some general guidelines for reporting errors in QEMU. >=20 > Signed-off-by: Llu=C3=ADs Vilanova > --- > HACKING | 33 +++++++++++++++++++++++++++++++++ > 1 file changed, 33 insertions(+) >=20 > diff --git a/HACKING b/HACKING > index 12fbc8a..f5783d4 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()'). abort() for unreachable code may be okay, but I'm not sure how to word that. Maybe "avoid use 'printf()' or 'exit()', and minimize use of 'abort()' situations that should be unreachable code". May be worth mentioning that if the user can trigger it (command line, hotplug, etc) then we want fatal; if it represents a programming bug that the user should not be able to trigger, then abort is okay. > + > +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 unimpl= imented s/unimplimented/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 t= he > +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 erro= r 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 th= e same > +constrains as the 'error_report_fatal' and 'error_report_abort' functi= ons. s/constrains/constraints/ --=20 Eric Blake eblake redhat com +1-919-301-3266 Libvirt virtualization library http://libvirt.org --Vj3kB8CQRgLpOHp8LPgGjjhRaLSqdrhX4 Content-Type: application/pgp-signature; name="signature.asc" Content-Description: OpenPGP digital signature Content-Disposition: attachment; filename="signature.asc" -----BEGIN PGP SIGNATURE----- Version: GnuPG v2 Comment: Public key at http://people.redhat.com/eblake/eblake.gpg Comment: Using GnuPG with Thunderbird - http://www.enigmail.net/ iQEcBAEBCAAGBQJWqo0sAAoJEKeha0olJ0NqMxAH/jh0qmdVmd27viconxMbwh8E WP8yT4Y+VIwO17vgw8JXarUuFKBPtEA02hBLu2eU56HhMR6xOoPbALfuQX60G8A/ sm/qHc+vmG4gkG459fjWvhsqp52M37Pe6k6YDZCcyOn+I2KfR1MPz+ORj33j43P0 tOaeOrdXVy4zCyNKuwdLxeXPsx4zzlOgw0cZ4mKmguW5NJhU4IQAlTIpUdwzzdgE 0/g4+6b1jTZtkKRL7a0Y/99y/lrBfaqWCpAUpxlRpVToNj6kuEy6sUhlwymPABpO rbejVXJRE+uqwFMVtUhUSSyR4+r4Dp8MaolV0P9bCWWrmnQCIO7JCEklO0TSK08= =iYfk -----END PGP SIGNATURE----- --Vj3kB8CQRgLpOHp8LPgGjjhRaLSqdrhX4--