From mboxrd@z Thu Jan 1 00:00:00 1970 Authentication-Results: mx.groups.io; dkim=missing; spf=pass (domain: redhat.com, ip: 209.132.183.28, mailfrom: lersek@redhat.com) Received: from mx1.redhat.com (mx1.redhat.com [209.132.183.28]) by groups.io with SMTP; Mon, 09 Sep 2019 05:25:13 -0700 Received: from smtp.corp.redhat.com (int-mx04.intmail.prod.int.phx2.redhat.com [10.5.11.14]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by mx1.redhat.com (Postfix) with ESMTPS id 6F58C308FC23; Mon, 9 Sep 2019 12:25:12 +0000 (UTC) Received: from lacos-laptop-7.usersys.redhat.com (ovpn-116-196.ams2.redhat.com [10.36.116.196]) by smtp.corp.redhat.com (Postfix) with ESMTP id 26ACA5D9DC; Mon, 9 Sep 2019 12:25:04 +0000 (UTC) Subject: Re: [edk2-devel] [PATCH edk2-CCSS 3/3] must comment: add rule for documenting spurious variable assignments To: =?UTF-8?Q?Philippe_Mathieu-Daud=c3=a9?= , devel@edk2.groups.io Cc: Andrew Fish , Leif Lindholm , Michael D Kinney , Rebecca Cran , Ard Biesheuvel References: <20190905183820.10312-1-lersek@redhat.com> <20190905183820.10312-4-lersek@redhat.com> <5d2526af-ed97-2267-b820-08deb064a278@redhat.com> From: "Laszlo Ersek" Message-ID: <1b1859ce-820e-d6c7-111e-16932c13e4c6@redhat.com> Date: Mon, 9 Sep 2019 14:25:04 +0200 User-Agent: Mozilla/5.0 (X11; Linux x86_64; rv:52.0) Gecko/20100101 Thunderbird/52.9.1 MIME-Version: 1.0 In-Reply-To: <5d2526af-ed97-2267-b820-08deb064a278@redhat.com> X-Scanned-By: MIMEDefang 2.79 on 10.5.11.14 X-Greylist: Sender IP whitelisted, not delayed by milter-greylist-4.5.16 (mx1.redhat.com [10.5.110.43]); Mon, 09 Sep 2019 12:25:12 +0000 (UTC) Content-Type: text/plain; charset=utf-8 Content-Language: en-US Content-Transfer-Encoding: quoted-printable On 09/06/19 10:13, Philippe Mathieu-Daud=C3=A9 wrote: > Hi Laszlo, >=20 > (Cc'ing Ard) >=20 > On 9/5/19 8:38 PM, Laszlo Ersek wrote: >> Problem statement from Ard: >> >>> Sometimes, the GCC compiler warns about variables potentially being u= sed >>> without having been initialized, while visual inspection reveals that >>> this is impossible. In such cases, we need to initialize such a varia= ble >>> to an arbitrary value only to avoid breaking the build, given our pol= icy >>> to treat warnings as errors. >=20 > This is annoying. >=20 > I suppose using CFLAGS+=3D'-Wno-uninitialized -Wmaybe-uninitialized' is > not an acceptable option. I don't have links handy, but around or before the time I filed TianoCore#607, we had gone through all the possibilities. The issue may have been possible to suppress with cmdline options for a particular toolchain version, but I'm fairly sure it was impossible to solve for all the toolchains simultaneously that edk2 supported at the time. >> >> In such cases we generally use >> >> LocalIntegerVariable =3D 0; >> >> and >> >> LocalPointerVariable =3D NULL; >> >> which takes care of the incorrect warning. However, it also makes the >> human analysis of any subsequent logic harder, because it suggests tha= t >> assigning that specific zero or NULL value to the local variable is >> *required* by the subsequent logic. >=20 > What about having explicit definitions to silent warnings, so we don't > need to add comments? >=20 > #define UNINITIALIZED_INTEGER 0 > #define UNINITIALIZED_POINTER NULL >=20 > Human review becomes trivial: >=20 > LocalPointerVariable =3D UNINITIALIZED_POINTER; We did consider macros too, if I remember correctly. It was not liked. (We definitely considered magic values, see 0xDEADBEEF below, and those were clearly rejected.) People really seemed to want zero / NULL values, open-coded. I disagreed, but accepted. The explicit comment suggestion was a compromise from my side, therefore. In this patch set, I wouldn't like to introduce a rule that is not based in current practice. The code base is already full of the above kind of zero / NULL assignment; the only coding style detail, from the rule being suggested, is the comment. While TianoCore#607 has been open, I've consistently directed developers to it, for the proposed syntax. Therefore, if you look at the code base today, you will find a large amount of the original un-annotated zero / NULL assignment (where you can't immediately tell whether they are algorithmically necessery or not), and a few instances of the wording proposed here. $ git grep 'incorrect compiler/analyzer' In that regard, this patch set aims to codify existing practice -- I just want to make the pattern more consistent. Thanks Laszlo >=20 >> In order to highlight such assignments, whose sole purpose is to suppr= ess >> invalid "use before init" warnings from compilers or static analysis >> tools, we should mandate comments such as: >> >> // >> // set LocalVariable to suppress incorrect compiler/analyzer warning= s >> // >> LocalVariable =3D 0; >> >> (Magic values such as 0xDEADBEEF, which would obviate the necessity of >> explicit comments, have been considered, and rejected for stylistic >> reasons.) >> >> Cc: Andrew Fish >> Cc: Leif Lindholm >> Cc: Michael D Kinney >> Cc: Rebecca Cran >> Ref: https://bugzilla.tianocore.org/show_bug.cgi?id=3D607 >> Signed-off-by: Laszlo Ersek >> --- >> 6_documenting_software/64_what_you_must_comment.md | 39 +++++++++++++= +++++++ >> README.md | 1 + >> 2 files changed, 40 insertions(+) >> >> diff --git a/6_documenting_software/64_what_you_must_comment.md b/6_do= cumenting_software/64_what_you_must_comment.md >> index abb2114bf5bc..9e51c2e45816 100644 >> --- a/6_documenting_software/64_what_you_must_comment.md >> +++ b/6_documenting_software/64_what_you_must_comment.md >> @@ -58,3 +58,42 @@ instance differs. >> =20 >> When possible, you should also list the requirements that are satisfi= ed by the >> code. >> + >> +### 6.4.6 Comment spurious variable assignments. >> + >> +A compiler or static code analyzer may warn that an object with autom= atic or >> +allocated storage duration is read without having been initialized, w= hile >> +visual inspection reveals that this is impossible. >> + >> +In order to suppress such a warning (which is emitted due to invalid = data flow >> +analysis), developers explicitly assign the affected object the value= to which >> +the same object would be initialized automatically, had the object st= atic >> +storage duration, and no initializer. (The value assigned could be ar= bitrary; >> +the above-mentioned value is chosen for stylistic reasons.) For examp= le: >> + >> +```c >> +UINTN LocalIntegerVariable; >> +VOID *LocalPointerVariable; >> + >> +LocalIntegerVariable =3D 0; >> +LocalPointerVariable =3D NULL; >> +``` >> + >> +This kind of assignment is difficult to distinguish from assignments = where the >> +initial value of an object is meaningful, and is consumed by other co= de without >> +an intervening assignment. Therefore, each such assignment must be do= cumented, >> +as follows: >> + >> +```c >> +UINTN LocalIntegerVariable; >> +VOID *LocalPointerVariable; >> + >> +// >> +// set LocalIntegerVariable to suppress incorrect compiler/analyzer w= arnings >> +// >> +LocalIntegerVariable =3D 0; >> +// >> +// set LocalPointerVariable to suppress incorrect compiler/analyzer w= arnings >> +// >> +LocalPointerVariable =3D NULL; >> +``` >> diff --git a/README.md b/README.md >> index e26133540368..0648819f0d3a 100644 >> --- a/README.md >> +++ b/README.md >> @@ -113,3 +113,4 @@ Copyright (c) 2006-2017, Intel Corporation. All ri= ghts reserved. >> | 2.2 | Convert to Gitbook = = | June 2017 | >> | | [#425](https://bugzilla.tianocore.org/show_bug.cgi?id=3D= 425) [CCS] clarify line breaking and indentation requirements for multi-l= ine function calls | | >> | | [#1656](https://bugzilla.tianocore.org/show_bug.cgi?id=3D= 1656) Update all Wiki pages for the BSD+Patent license change with SPDX i= dentifiers | | >> +| | [#607](https://bugzilla.tianocore.org/show_bug.cgi?id=3D= 607) Document code comment requirements for spurious variable assignments= | | >>