From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: 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 Authentication-Results: sourceware.org; dmarc=pass (p=none dis=none) header.from=adacore.com Authentication-Results: sourceware.org; spf=pass smtp.mailfrom=adacore.com Received: by mail-wm1-x32d.google.com with SMTP id d5so6356422wms.5 for ; Tue, 06 Sep 2022 00:15:56 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=adacore.com; s=google; h=content-transfer-encoding:content-disposition:mime-version :message-id:subject:cc:to:from:date:from:to:cc:subject:date; bh=3NTA5FL7pxDgIUQUi3W/iX+LATgJFoB84En/7CZwR0o=; b=dXZUO1JVWpAYnnjNqNiHl+IupaXg06Czsi7txGf+x0Rg7pUCySCystkNRJIamUPnQx Z18bphiH+z9uhTtNvk86LPuOsbpdBsYUBawhpz50PSysaL5Ez+7+2OoroGCern4fzMuT vRjHNi1zikIe0M6qICTfg/Zd/dqz8PlBWR/feqfX7Q9kqsWCO0iQsPKurLWhJhiukY3a LfKRYC6lBEnjiIYQxIQHtdtPRSQOtydq7NI3hGz/zmM6GRCRtJ/qnNvQK268YkbohD5v jJWiHyTJ/mgExoe/hU8JYq1xbpUrrHSNzk4IRvqLYpGBJaZn1alS/QCUf+z5vabUgjMh 4Lfw== 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-Google-Smtp-Source: AA6agR4f421VV4i/og09+Xlxa3/p9yHGJJjeEHaUeY3A1qi6fIWO/COs3eim993OZXuoQze6QsP3PA== 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 From: Marc =?iso-8859-1?Q?Poulhi=E8s?= To: gcc-patches@gcc.gnu.org Cc: Steve Baird Subject: [Ada] Improve documentation of validation checking control switches Message-ID: <20220906071554.GA1280421@poulhies-Precision-5550> MIME-Version: 1.0 Content-Type: multipart/mixed; boundary="fdj2RfSjLxBAspz7" Content-Disposition: inline Content-Transfer-Encoding: 8bit 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 List-Id: --fdj2RfSjLxBAspz7 Content-Type: text/plain; charset=us-ascii Content-Disposition: inline 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. --fdj2RfSjLxBAspz7 Content-Type: text/x-diff; charset=utf-8 Content-Disposition: attachment; filename="patch.diff" Content-Transfer-Encoding: 8bit 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) --fdj2RfSjLxBAspz7--