From mboxrd@z Thu Jan 1 00:00:00 1970 Received: from eggs.gnu.org ([2001:4830:134:3::10]:47982) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1aLGNz-0002Ir-IZ for qemu-devel@nongnu.org; Mon, 18 Jan 2016 15:26:48 -0500 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1aLGNw-0003Th-CH for qemu-devel@nongnu.org; Mon, 18 Jan 2016 15:26:47 -0500 Received: from mx1.redhat.com ([209.132.183.28]:40164) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1aLGNw-0003Td-4j for qemu-devel@nongnu.org; Mon, 18 Jan 2016 15:26:44 -0500 References: <145286604004.29455.1509463776346981362.stgit@localhost> <145286604762.29455.8630766735054984295.stgit@localhost> From: Eric Blake Message-ID: <569D4A82.5000506@redhat.com> Date: Mon, 18 Jan 2016 13:26:42 -0700 MIME-Version: 1.0 In-Reply-To: <145286604762.29455.8630766735054984295.stgit@localhost> Content-Type: multipart/signed; micalg=pgp-sha256; protocol="application/pgp-signature"; boundary="0XCbC4oogH4q3lq4A72ixMGjsKxtAx1WK" Subject: Re: [Qemu-devel] [PATCH v3 ] 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) --0XCbC4oogH4q3lq4A72ixMGjsKxtAx1WK Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: quoted-printable On 01/15/2016 06:54 AM, Llu=C3=ADs Vilanova wrote: > Gives some general guidelines for reporting errors in QEMU. >=20 > Signed-off-by: Llu=C3=ADs Vilanova > --- > HACKING | 36 ++++++++++++++++++++++++++++++++++++ > 1 file changed, 36 insertions(+) >=20 > +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. s/on/in/ > + > +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). Maybe: "not directly triggered". After all, we DO have places where Error is used which can ultimately be traced to a user command (such as in QMP commands), but where the local code can also be called internally; the use of Error at the local level then lets us leave it up to the caller whether to report a message (because the caller has more context). > + > +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"); This paradigm doesn't appear anywhere in the current code base (hw/ppc/spapr*.c has a few cases of error_setg(&error_abort), but nothing directly passes error_fatal). It's a bit odd to document something that isn't actually used. > + > +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 s/Specially/Specifically/ > +and immediately terminate QEMU. > + > +WARNING: Do *not* use 'error_fatal' or 'error_abort' for errors that a= re (or can > +be) triggered by guest code (e.g., some unimplimented corner case in g= uest code s/unimplimented/unimplemented/ > +translation or device code). Otherwise that can be abused by guest cod= e to > +terminate QEMU. Instead, you should use the 'error_report()' routine. But a definite improvement over v2. I think we're getting closer to a good summary. --=20 Eric Blake eblake redhat com +1-919-301-3266 Libvirt virtualization library http://libvirt.org --0XCbC4oogH4q3lq4A72ixMGjsKxtAx1WK 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/ iQEcBAEBCAAGBQJWnUqCAAoJEKeha0olJ0Nqtr4IAJOpnFVFg9QzPU9CRcMMOrYn iMROjRhoZMENLgkawzneQgd0P5QoH0vpca3hWz6eAlAJJRT0CJHoqWQ6fDzQdeKG nWZpUzaVHV83tbSQCSePpTkW2jVKCRwhmaTUSkO+EysYacpTNcz4iVop3Q9bHHP6 b725UCNou/7QxiS+w8VStJb8ZtYylDeqqI3ryIzw7bThs5WKycPEjtiwsKSfPax2 0yP9j2/rBVdwGy5r4CkkC8S4RJmDhGMEZOzBeYPCqlQRK2yp/bwyutHyKnGxXWNN dE02FAtgF3dcdgyoPJTIRLboqMhjGCdkS5aWxBbxvdhcSR3iHOo2Vj5cx+mhKaQ= =cZ2X -----END PGP SIGNATURE----- --0XCbC4oogH4q3lq4A72ixMGjsKxtAx1WK--