From nobody Thu Mar 28 19:58:07 2024 Delivered-To: importer@patchew.org Received-SPF: pass (zoho.com: domain of groups.io designates 66.175.222.12 as permitted sender) client-ip=66.175.222.12; envelope-from=bounce+27952+46935+1787277+3901457@groups.io; helo=web01.groups.io; Authentication-Results: mx.zohomail.com; dkim=pass; spf=pass (zoho.com: domain of groups.io designates 66.175.222.12 as permitted sender) smtp.mailfrom=bounce+27952+46935+1787277+3901457@groups.io; dmarc=fail(p=none dis=none) header.from=redhat.com ARC-Seal: i=1; a=rsa-sha256; t=1567708709; cv=none; d=zoho.com; s=zohoarc; b=XrsSPGVyc8HalLs9W03WY8wbtrwUkv9RqAahCA4zC2iTBe6kuk/QtErJqBGhQT6yZNDdliYuZ3nQexPPJMN9ne9vRrQKR0THEkhvgs1M0nP9KuPc1M2zTCtWAK48u2aqz4wB/kOLteRHgbNe99D808ETgPsI09CMjLHw87j+MRE= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zoho.com; s=zohoarc; t=1567708709; h=Content-Transfer-Encoding:Cc:Date:From:In-Reply-To:List-Id:List-Unsubscribe:MIME-Version:Message-ID:Reply-To:References:Sender:Subject:To:ARC-Authentication-Results; bh=ODQcbXI8gvb4acuf4qsWpZhESe2Cn2auNk3lp5cf2mQ=; b=TG/7joSEetP1eR2Ql1+lAS/uaBZtglfu1JffybfKCCoQoqoYDYEjnGd1oFM6M9OYQncloOk0vr0PxzPbwYuU3WvIzFhAvo+3wC1QRmvg0ZsuGjr8QjcWkOXOkpOsiL7iFHd3fYnMCngN1k7LdaA2b0bMWTJtYZrHQ6nhDqFvyxY= ARC-Authentication-Results: i=1; mx.zoho.com; dkim=pass; spf=pass (zoho.com: domain of groups.io designates 66.175.222.12 as permitted sender) smtp.mailfrom=bounce+27952+46935+1787277+3901457@groups.io; dmarc=fail header.from= (p=none dis=none) header.from= Received: from web01.groups.io (web01.groups.io [66.175.222.12]) by mx.zohomail.com with SMTPS id 1567708709811249.43074264637073; Thu, 5 Sep 2019 11:38:29 -0700 (PDT) Return-Path: X-Received: from mx1.redhat.com (mx1.redhat.com [209.132.183.28]) by groups.io with SMTP; Thu, 05 Sep 2019 11:38:28 -0700 X-Received: from smtp.corp.redhat.com (int-mx05.intmail.prod.int.phx2.redhat.com [10.5.11.15]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by mx1.redhat.com (Postfix) with ESMTPS id 926601DA2; Thu, 5 Sep 2019 18:38:28 +0000 (UTC) X-Received: from lacos-laptop-7.usersys.redhat.com (ovpn-116-133.ams2.redhat.com [10.36.116.133]) by smtp.corp.redhat.com (Postfix) with ESMTP id 3FAF15D712; Thu, 5 Sep 2019 18:38:27 +0000 (UTC) From: "Laszlo Ersek" To: edk2-devel-groups-io Cc: Andrew Fish , Leif Lindholm , Michael D Kinney , Rebecca Cran Subject: [edk2-devel] [PATCH edk2-CCSS 3/3] must comment: add rule for documenting spurious variable assignments Date: Thu, 5 Sep 2019 20:38:20 +0200 Message-Id: <20190905183820.10312-4-lersek@redhat.com> In-Reply-To: <20190905183820.10312-1-lersek@redhat.com> References: <20190905183820.10312-1-lersek@redhat.com> MIME-Version: 1.0 X-Scanned-By: MIMEDefang 2.79 on 10.5.11.15 X-Greylist: Sender IP whitelisted, not delayed by milter-greylist-4.6.2 (mx1.redhat.com [10.5.110.71]); Thu, 05 Sep 2019 18:38:28 +0000 (UTC) Precedence: Bulk List-Unsubscribe: Sender: devel@edk2.groups.io List-Id: Mailing-List: list devel@edk2.groups.io; contact devel+owner@edk2.groups.io Reply-To: devel@edk2.groups.io,lersek@redhat.com Content-Transfer-Encoding: quoted-printable DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=groups.io; q=dns/txt; s=20140610; t=1567708709; bh=MmG4QhObsIxgJzt6Xqyc1YcfuxYSPiuCGo5WZvszigA=; h=Cc:Date:From:Reply-To:Subject:To; b=qB8m8RlG8Bz3M8hIXuss6dDiG+Os54lwq+gz3lFOEX/01xsPwpulHTjaEN/c3qK12zB p5ZOS7LsPYet337KAVX5n/zIz1Ee73Gi+97sBMm4QvHWXv2H0Z8eWzbOayTrRziB/OW3U lEGnuMPRgyT2UQiU8liiBICO6LesZlHXomU= X-ZohoMail-DKIM: pass (identity @groups.io) Content-Type: text/plain; charset="utf-8" Problem statement from Ard: > Sometimes, the GCC compiler warns about variables potentially being used > without having been initialized, while visual inspection reveals that > this is impossible. In such cases, we need to initialize such a variable > to an arbitrary value only to avoid breaking the build, given our policy > to treat warnings as errors. 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 that assigning that specific zero or NULL value to the local variable is *required* by the subsequent logic. In order to highlight such assignments, whose sole purpose is to suppress invalid "use before init" warnings from compilers or static analysis tools, we should mandate comments such as: // // set LocalVariable to suppress incorrect compiler/analyzer warnings // 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 Reviewed-by: Philippe Mathieu-Daude --- 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_documen= ting_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 satisfied by= the code. + +### 6.4.6 Comment spurious variable assignments. + +A compiler or static code analyzer may warn that an object with automatic = or +allocated storage duration is read without having been initialized, while +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 w= hich +the same object would be initialized automatically, had the object static +storage duration, and no initializer. (The value assigned could be arbitra= ry; +the above-mentioned value is chosen for stylistic reasons.) For example: + +```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 code wi= thout +an intervening assignment. Therefore, each such assignment must be documen= ted, +as follows: + +```c +UINTN LocalIntegerVariable; +VOID *LocalPointerVariable; + +// +// set LocalIntegerVariable to suppress incorrect compiler/analyzer warnin= gs +// +LocalIntegerVariable =3D 0; +// +// set LocalPointerVariable to suppress incorrect compiler/analyzer warnin= gs +// +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 rights = reserved. | 2.2 | Convert to Gitbook = = | June 2017 | | | [#425](https://bugzilla.tianocore.org/show_bug.cgi?id=3D425) = [CCS] clarify line breaking and indentation requirements for multi-line fun= ction calls | | | | [#1656](https://bugzilla.tianocore.org/show_bug.cgi?id=3D1656= ) Update all Wiki pages for the BSD+Patent license change with SPDX identif= iers | | +| | [#607](https://bugzilla.tianocore.org/show_bug.cgi?id=3D607) = Document code comment requirements for spurious variable assignments = | | --=20 2.19.1.3.g30247aa5d201 -=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D- Groups.io Links: You receive all messages sent to this group. View/Reply Online (#46935): https://edk2.groups.io/g/devel/message/46935 Mute This Topic: https://groups.io/mt/33157544/1787277 Group Owner: devel+owner@edk2.groups.io Unsubscribe: https://edk2.groups.io/g/devel/unsub [importer@patchew.org] -=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D-