From patchwork Tue Sep 6 07:15:54 2022 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-Patchwork-Submitter: =?utf-8?q?Marc_Poulhi=C3=A8s?= X-Patchwork-Id: 1026 Return-Path: Delivered-To: ouuuleilei@gmail.com Received: by 2002:a5d:5044:0:0:0:0:0 with SMTP id h4csp506604wrt; Tue, 6 Sep 2022 00:28:38 -0700 (PDT) X-Google-Smtp-Source: AA6agR776gHEviAW145BsqEoynUevDhkNQKfTT++QlOJu1rOvWvWoTLk9fTTCSg5sY3y+WPfsnC/ X-Received: by 2002:a05:6402:2073:b0:44e:3555:5fcd with SMTP id bd19-20020a056402207300b0044e35555fcdmr9330148edb.82.1662449318631; Tue, 06 Sep 2022 00:28:38 -0700 (PDT) ARC-Seal: i=1; a=rsa-sha256; t=1662449318; cv=none; d=google.com; s=arc-20160816; b=nyX5gZIGuLqtES7XGobDa0dNJFJwUy3q2ycwG5f4xTppzC8nnn3R02jkpViFhHQxNs r60euWMAX3zcw6Pe8USstlwBWjskFx412WsixBNEvrB56phhZxeYgtDoMIJOuwmT+q2l B9wV0IVzL1Brkyqp1g+DpdfbwSqGa5t9IhIyfCeunG1rdyonwD0eWamRxcfU2i/qYgic NmbnPxoGTF26vKS/aOd8YB20ZwzEKNVC6RVqUX/6Ss+kEu8VbRWV1QHkJanriK7gqDij opbRytvmjPtbrC6RXB6IN6XeYStxIZjnNlDd9Rll7Jc017xaBmTGCT+CJOd5H/Qli60Q vm/g== ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=google.com; s=arc-20160816; h=sender:errors-to:cc:reply-to:from:list-subscribe:list-help :list-post:list-archive:list-unsubscribe:list-id:precedence :content-transfer-encoding:content-disposition:mime-version :message-id:subject:to:date:dmarc-filter:delivered-to:dkim-signature :dkim-filter; bh=3NTA5FL7pxDgIUQUi3W/iX+LATgJFoB84En/7CZwR0o=; b=jZRjSnogP3UiM/i8z14KQPw5SyzSxZW+6DHJQQng6zpwY0/BR57Uh+dqk5cK5/mf3J 9PqdC1rojhXU/Fjnr912qMs2WKA8cbyuV9e/NrLm/5Hl23a8JkAbq0PJkyHwMFna2+55 3kUKbT/drHqiF0dXBWPSkrtehNC9BgOzklRo8H+VKvkhCGp9RTFG/7v40IvJsUesFutQ +BIkqXx1yGcrauiUXg9/IQ07wi+RQOSlnLUOcwUxUBPcE5gCn7Wn7TojX3N2zTfK22Q+ dyAI7G/2dBlT0jICyEW4T3GMNjjbarh4dAc9hSfAFdvs2t83nNlcN4jq0Q6Zbb2mGEnb 0daA== ARC-Authentication-Results: i=1; mx.google.com; dkim=pass header.i=@gcc.gnu.org header.s=default header.b=LgcXI1fC; spf=pass (google.com: domain of gcc-patches-bounces+ouuuleilei=gmail.com@gcc.gnu.org designates 2620:52:3:1:0:246e:9693:128c as permitted sender) smtp.mailfrom="gcc-patches-bounces+ouuuleilei=gmail.com@gcc.gnu.org"; dmarc=pass (p=NONE sp=NONE dis=NONE) header.from=gnu.org Received: from sourceware.org (server2.sourceware.org. [2620:52:3:1:0:246e:9693:128c]) by mx.google.com with ESMTPS id h11-20020a056402280b00b00447cb9f8cacsi9650194ede.336.2022.09.06.00.28.38 for (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Tue, 06 Sep 2022 00:28:38 -0700 (PDT) Received-SPF: pass (google.com: domain of gcc-patches-bounces+ouuuleilei=gmail.com@gcc.gnu.org designates 2620:52:3:1:0:246e:9693:128c as permitted sender) client-ip=2620:52:3:1:0:246e:9693:128c; Authentication-Results: mx.google.com; dkim=pass header.i=@gcc.gnu.org header.s=default header.b=LgcXI1fC; spf=pass (google.com: domain of gcc-patches-bounces+ouuuleilei=gmail.com@gcc.gnu.org designates 2620:52:3:1:0:246e:9693:128c as permitted sender) smtp.mailfrom="gcc-patches-bounces+ouuuleilei=gmail.com@gcc.gnu.org"; dmarc=pass (p=NONE sp=NONE dis=NONE) header.from=gnu.org Received: from server2.sourceware.org (localhost [IPv6:::1]) by sourceware.org (Postfix) with ESMTP id 0556F395A458 for ; Tue, 6 Sep 2022 07:22:29 +0000 (GMT) DKIM-Filter: OpenDKIM Filter v2.11.0 sourceware.org 0556F395A458 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gcc.gnu.org; s=default; t=1662448949; bh=3NTA5FL7pxDgIUQUi3W/iX+LATgJFoB84En/7CZwR0o=; h=Date:To:Subject:List-Id:List-Unsubscribe:List-Archive:List-Post: List-Help:List-Subscribe:From:Reply-To:Cc:From; b=LgcXI1fCwOCwm6bdq7dXZ7XhVAk074290RjA2DZHNt6f62DqX5xzLPUIhN4ARs035 EwlF8+huvXO8ZiFo1zFue1U7eDDZCCvSKYfvKLYOkVMBd9LYxGvrQNFHgsfHxGYvPH 8POqLQ/e5Tse6ksCYXuH65x/YHtILf1YdWLT50No= X-Original-To: gcc-patches@gcc.gnu.org Delivered-To: gcc-patches@gcc.gnu.org Received: from mail-wm1-x32d.google.com (mail-wm1-x32d.google.com [IPv6:2a00:1450:4864:20::32d]) by sourceware.org (Postfix) with ESMTPS id 2C77D3850868 for ; Tue, 6 Sep 2022 07:15:56 +0000 (GMT) DMARC-Filter: OpenDMARC Filter v1.4.1 sourceware.org 2C77D3850868 Received: by mail-wm1-x32d.google.com with SMTP id d5so6356422wms.5 for ; Tue, 06 Sep 2022 00:15:56 -0700 (PDT) X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20210112; h=content-transfer-encoding:content-disposition:mime-version :message-id:subject:cc:to:from:date:x-gm-message-state:from:to:cc :subject:date; bh=3NTA5FL7pxDgIUQUi3W/iX+LATgJFoB84En/7CZwR0o=; b=cP0EdRjy+teAyUhjmQIhmoalkrE8q2w/ZEgwKliv/TZ0isxzD7t47ndBpyREUwsmXO j59rY6SdRdff4i83k1QdOmG+Be0BwO8KUk0fGgU2qnvTfAgoudvKhaFpkJjb0N90R6U8 +0znlqf0LeaUfL8pzcvIwOs0EqZyOpozlna5toITkVYHsBmC/Qnni16th3hvZeSYevRE Z/DeXEHbq1uxjpr7CELpx/mjoQQ2speexOIQyWGhtQ6t8OSfEYiYGdxPd+1I7xT1aSQu CZ3LHdTUYmQTH5rS9n7vhkYvg9CStq4jVAe2MUJQV1H2Nd7Wkxkjy3ZNTyGT5/iE9BKY lOnA== X-Gm-Message-State: ACgBeo0y1YhmJ1VDOaTBKwWTihdwbfQi2m12cDQB5w5F/PdsLdpuu18m VM1rqA8JS4Hy6uA+PL2U1Jn1N1kVAa/36g== X-Received: by 2002:a7b:c844:0:b0:3a9:70d2:bf23 with SMTP id c4-20020a7bc844000000b003a970d2bf23mr12639299wml.165.1662448555819; Tue, 06 Sep 2022 00:15:55 -0700 (PDT) Received: from poulhies-Precision-5550 (static-176-191-105-132.ftth.abo.bbox.fr. [176.191.105.132]) by smtp.gmail.com with ESMTPSA id bs6-20020a056000070600b00228d67db06esm2095164wrb.21.2022.09.06.00.15.55 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Tue, 06 Sep 2022 00:15:55 -0700 (PDT) Date: Tue, 6 Sep 2022 09:15:54 +0200 To: gcc-patches@gcc.gnu.org Subject: [Ada] Improve documentation of validation checking control switches Message-ID: <20220906071554.GA1280421@poulhies-Precision-5550> MIME-Version: 1.0 Content-Disposition: inline X-Spam-Status: No, score=-13.0 required=5.0 tests=BAYES_00, DKIM_SIGNED, DKIM_VALID, DKIM_VALID_AU, DKIM_VALID_EF, GIT_PATCH_0, RCVD_IN_DNSWL_NONE, SPF_HELO_NONE, SPF_PASS, TXREP, T_SCC_BODY_TEXT_LINE autolearn=ham autolearn_force=no version=3.4.6 X-Spam-Checker-Version: SpamAssassin 3.4.6 (2021-04-09) on server2.sourceware.org X-BeenThere: gcc-patches@gcc.gnu.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: Gcc-patches mailing list List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-Patchwork-Original-From: =?utf-8?q?Marc_Poulhi=C3=A8s_via_Gcc-patches?= From: =?utf-8?q?Marc_Poulhi=C3=A8s?= Reply-To: Marc =?iso-8859-1?q?Poulhi=E8s?= Cc: Steve Baird Errors-To: gcc-patches-bounces+ouuuleilei=gmail.com@gcc.gnu.org Sender: "Gcc-patches" X-getmail-retrieved-from-mailbox: =?utf-8?q?INBOX?= X-GMAIL-THRID: =?utf-8?q?1743204456812625726?= X-GMAIL-MSGID: =?utf-8?q?1743204456812625726?= Correct incorrect text and clarify unclear text that has been identified in the "Validity Checking" section of the GNAT UG. Tested on x86_64-pc-linux-gnu, committed on trunk gcc/ada/ * doc/gnat_ugn/building_executable_programs_with_gnat.rst: Improve -gnatVa, -gnatVc, -gnatVd, -gnatVe, -gnatVf, -gnatVo, -gnatVp, -gnatVr, and -gnatVs switch descriptions. * gnat_ugn.texi: Regenerate. diff --git a/gcc/ada/doc/gnat_ugn/building_executable_programs_with_gnat.rst b/gcc/ada/doc/gnat_ugn/building_executable_programs_with_gnat.rst --- a/gcc/ada/doc/gnat_ugn/building_executable_programs_with_gnat.rst +++ b/gcc/ada/doc/gnat_ugn/building_executable_programs_with_gnat.rst @@ -4455,7 +4455,7 @@ to the default checks required by Ada as described above. All validity checks are turned on. That is, :switch:`-gnatVa` is - equivalent to ``gnatVcdfimoprst``. + equivalent to ``gnatVcdefimoprst``. .. index:: -gnatVc (gcc) @@ -4463,8 +4463,8 @@ to the default checks required by Ada as described above. :switch:`-gnatVc` *Validity checks for copies.* - The right hand side of assignments, and the initializing values of - object declarations are validity checked. + The right-hand side of assignments, and the (explicit) initializing values + of object declarations are validity checked. .. index:: -gnatVd (gcc) @@ -4472,12 +4472,14 @@ to the default checks required by Ada as described above. :switch:`-gnatVd` *Default (RM) validity checks.* - Some validity checks are done by default following normal Ada semantics - (RM 13.9.1 (9-11)). - A check is done in case statements that the expression is within the range - of the subtype. If it is not, Constraint_Error is raised. - For assignments to array components, a check is done that the expression used - as index is within the range. If it is not, Constraint_Error is raised. + Some validity checks are required by Ada (see RM 13.9.1 (9-11)); these + (and only these) validity checks are enabled by default. + For case statements (and case expressions) that lack a "when others =>" + choice, a check is made that the value of the selector expression + belongs to its nominal subtype. If it does not, Constraint_Error is raised. + For assignments to array components (and for indexed components in some + other contexts), a check is made that each index expression belongs to the + corresponding index subtype. If it does not, Constraint_Error is raised. Both these validity checks may be turned off using switch :switch:`-gnatVD`. They are turned on by default. If :switch:`-gnatVD` is specified, a subsequent switch :switch:`-gnatVd` will leave the checks turned on. @@ -4490,28 +4492,31 @@ to the default checks required by Ada as described above. .. index:: -gnatVe (gcc) :switch:`-gnatVe` - *Validity checks for elementary components.* - - In the absence of this switch, assignments to record or array components are - not validity checked, even if validity checks for assignments generally - (:switch:`-gnatVc`) are turned on. In Ada, assignment of composite values do not - require valid data, but assignment of individual components does. So for - example, there is a difference between copying the elements of an array with a - slice assignment, compared to assigning element by element in a loop. This - switch allows you to turn off validity checking for components, even when they - are assigned component by component. + *Validity checks for scalar components.* + In the absence of this switch, assignments to scalar components of + enclosing record or array objects are not validity checked, even if + validity checks for assignments generally (:switch:`-gnatVc`) are turned on. + Specifying this switch enables such checks. + This switch has no effect if the :switch:`-gnatVc` switch is not specified. .. index:: -gnatVf (gcc) :switch:`-gnatVf` *Validity checks for floating-point values.* - In the absence of this switch, validity checking occurs only for discrete - values. If :switch:`-gnatVf` is specified, then validity checking also applies + Specifying this switch enables validity checking for floating-point + values in the same contexts where validity checking is enabled for + other scalar values. + In the absence of this switch, validity checking is not performed for + floating-point values. This takes precedence over other statements about + performing validity checking for scalar objects in various scenarios. + One way to look at it is that if this switch is not set, then whenever + any of the other rules in this section use the word "scalar" they + really mean "scalar and not floating-point". + If :switch:`-gnatVf` is specified, then validity checking also applies for floating-point values, and NaNs and infinities are considered invalid, - as well as out of range values for constrained types. Note that this means - that standard IEEE infinity mode is not allowed. The exact contexts + as well as out-of-range values for constrained types. The exact contexts in which floating-point values are checked depends on the setting of other options. For example, :switch:`-gnatVif` or :switch:`-gnatVfi` (the order does not matter) specifies that floating-point parameters of mode @@ -4558,7 +4563,8 @@ to the default checks required by Ada as described above. :switch:`-gnatVo` *Validity checks for operator and attribute operands.* - Arguments for predefined operators and attributes are validity checked. + Scalar arguments for predefined operators and for attributes are + validity checked. This includes all operators in package ``Standard``, the shift operators defined as intrinsic in package ``Interfaces`` and operands for attributes such as ``Pos``. Checks are also made @@ -4572,22 +4578,22 @@ to the default checks required by Ada as described above. :switch:`-gnatVp` *Validity checks for parameters.* - This controls the treatment of parameters within a subprogram (as opposed - to :switch:`-gnatVi` and :switch:`-gnatVm` which control validity testing - of parameters on a call. If either of these call options is used, then - normally an assumption is made within a subprogram that the input arguments - have been validity checking at the point of call, and do not need checking - again within a subprogram). If :switch:`-gnatVp` is set, then this assumption - is not made, and parameters are not assumed to be valid, so their validity - will be checked (or rechecked) within the subprogram. - + This controls the treatment of formal parameters within a subprogram (as + opposed to :switch:`-gnatVi` and :switch:`-gnatVm`, which control validity + testing of actual parameters of a call). If either of these call options is + specified, then normally an assumption is made within a subprogram that + the validity of any incoming formal parameters of the corresponding mode(s) + has already been checked at the point of call and does not need rechecking. + If :switch:`-gnatVp` is set, then this assumption is not made and so their + validity may be checked (or rechecked) within the subprogram. If neither of + the two call-related options is specified, then this switch has no effect. .. index:: -gnatVr (gcc) :switch:`-gnatVr` *Validity checks for function returns.* - The expression in ``return`` statements in functions is validity + The expression in simple ``return`` statements in functions is validity checked. @@ -4596,9 +4602,10 @@ to the default checks required by Ada as described above. :switch:`-gnatVs` *Validity checks for subscripts.* - All subscripts expressions are checked for validity, whether they appear - on the right side or left side (in default mode only left side subscripts - are validity checked). + All subscript expressions are checked for validity, whatever context + they occur in (in default mode some subscripts are not validity checked; + for example, validity checking may be omitted in some cases involving + a read of a component of an array). .. index:: -gnatVt (gcc) diff --git a/gcc/ada/gnat_ugn.texi b/gcc/ada/gnat_ugn.texi --- a/gcc/ada/gnat_ugn.texi +++ b/gcc/ada/gnat_ugn.texi @@ -12984,7 +12984,7 @@ to the default checks required by Ada as described above. All validity checks are turned on. That is, @code{-gnatVa} is -equivalent to @code{gnatVcdfimoprst}. +equivalent to @code{gnatVcdefimoprst}. @end table @geindex -gnatVc (gcc) @@ -12996,8 +12996,8 @@ equivalent to @code{gnatVcdfimoprst}. `Validity checks for copies.' -The right hand side of assignments, and the initializing values of -object declarations are validity checked. +The right-hand side of assignments, and the (explicit) initializing values +of object declarations are validity checked. @end table @geindex -gnatVd (gcc) @@ -13009,12 +13009,14 @@ object declarations are validity checked. `Default (RM) validity checks.' -Some validity checks are done by default following normal Ada semantics -(RM 13.9.1 (9-11)). -A check is done in case statements that the expression is within the range -of the subtype. If it is not, Constraint_Error is raised. -For assignments to array components, a check is done that the expression used -as index is within the range. If it is not, Constraint_Error is raised. +Some validity checks are required by Ada (see RM 13.9.1 (9-11)); these +(and only these) validity checks are enabled by default. +For case statements (and case expressions) that lack a “when others =>” +choice, a check is made that the value of the selector expression +belongs to its nominal subtype. If it does not, Constraint_Error is raised. +For assignments to array components (and for indexed components in some +other contexts), a check is made that each index expression belongs to the +corresponding index subtype. If it does not, Constraint_Error is raised. Both these validity checks may be turned off using switch @code{-gnatVD}. They are turned on by default. If @code{-gnatVD} is specified, a subsequent switch @code{-gnatVd} will leave the checks turned on. @@ -13031,16 +13033,13 @@ overwriting may occur. @item @code{-gnatVe} -`Validity checks for elementary components.' +`Validity checks for scalar components.' -In the absence of this switch, assignments to record or array components are -not validity checked, even if validity checks for assignments generally -(@code{-gnatVc}) are turned on. In Ada, assignment of composite values do not -require valid data, but assignment of individual components does. So for -example, there is a difference between copying the elements of an array with a -slice assignment, compared to assigning element by element in a loop. This -switch allows you to turn off validity checking for components, even when they -are assigned component by component. +In the absence of this switch, assignments to scalar components of +enclosing record or array objects are not validity checked, even if +validity checks for assignments generally (@code{-gnatVc}) are turned on. +Specifying this switch enables such checks. +This switch has no effect if the @code{-gnatVc} switch is not specified. @end table @geindex -gnatVf (gcc) @@ -13052,11 +13051,18 @@ are assigned component by component. `Validity checks for floating-point values.' -In the absence of this switch, validity checking occurs only for discrete -values. If @code{-gnatVf} is specified, then validity checking also applies +Specifying this switch enables validity checking for floating-point +values in the same contexts where validity checking is enabled for +other scalar values. +In the absence of this switch, validity checking is not performed for +floating-point values. This takes precedence over other statements about +performing validity checking for scalar objects in various scenarios. +One way to look at it is that if this switch is not set, then whenever +any of the other rules in this section use the word “scalar” they +really mean “scalar and not floating-point”. +If @code{-gnatVf} is specified, then validity checking also applies for floating-point values, and NaNs and infinities are considered invalid, -as well as out of range values for constrained types. Note that this means -that standard IEEE infinity mode is not allowed. The exact contexts +as well as out-of-range values for constrained types. The exact contexts in which floating-point values are checked depends on the setting of other options. For example, @code{-gnatVif} or @code{-gnatVfi} (the order does not matter) specifies that floating-point parameters of mode @@ -13119,7 +13125,8 @@ is used, it cancels any other @code{-gnatV} previously issued. `Validity checks for operator and attribute operands.' -Arguments for predefined operators and attributes are validity checked. +Scalar arguments for predefined operators and for attributes are +validity checked. This includes all operators in package @code{Standard}, the shift operators defined as intrinsic in package @code{Interfaces} and operands for attributes such as @code{Pos}. Checks are also made @@ -13137,14 +13144,15 @@ also made on explicit ranges using @code{..} (e.g., slices, loops etc). `Validity checks for parameters.' -This controls the treatment of parameters within a subprogram (as opposed -to @code{-gnatVi} and @code{-gnatVm} which control validity testing -of parameters on a call. If either of these call options is used, then -normally an assumption is made within a subprogram that the input arguments -have been validity checking at the point of call, and do not need checking -again within a subprogram). If @code{-gnatVp} is set, then this assumption -is not made, and parameters are not assumed to be valid, so their validity -will be checked (or rechecked) within the subprogram. +This controls the treatment of formal parameters within a subprogram (as +opposed to @code{-gnatVi} and @code{-gnatVm}, which control validity +testing of actual parameters of a call). If either of these call options is +specified, then normally an assumption is made within a subprogram that +the validity of any incoming formal parameters of the corresponding mode(s) +has already been checked at the point of call and does not need rechecking. +If @code{-gnatVp} is set, then this assumption is not made and so their +validity may be checked (or rechecked) within the subprogram. If neither of +the two call-related options is specified, then this switch has no effect. @end table @geindex -gnatVr (gcc) @@ -13156,7 +13164,7 @@ will be checked (or rechecked) within the subprogram. `Validity checks for function returns.' -The expression in @code{return} statements in functions is validity +The expression in simple @code{return} statements in functions is validity checked. @end table @@ -13169,9 +13177,10 @@ checked. `Validity checks for subscripts.' -All subscripts expressions are checked for validity, whether they appear -on the right side or left side (in default mode only left side subscripts -are validity checked). +All subscript expressions are checked for validity, whatever context +they occur in (in default mode some subscripts are not validity checked; +for example, validity checking may be omitted in some cases involving +a read of a component of an array). @end table @geindex -gnatVt (gcc)