From patchwork Thu Oct 19 14:41:53 2023 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: 155625 Return-Path: Delivered-To: ouuuleilei@gmail.com Received: by 2002:a05:612c:2010:b0:403:3b70:6f57 with SMTP id fe16csp433124vqb; Thu, 19 Oct 2023 07:42:43 -0700 (PDT) X-Google-Smtp-Source: AGHT+IGROyRmc2V0Q2TCC+8sULvTasxFMR2SwIyt0Et0ZBtnJ/CqG8tWxF5e22+w+JHt2hmsey3w X-Received: by 2002:a25:6d05:0:b0:d9b:417:139c with SMTP id i5-20020a256d05000000b00d9b0417139cmr2236570ybc.60.1697726562818; Thu, 19 Oct 2023 07:42:42 -0700 (PDT) ARC-Seal: i=2; a=rsa-sha256; t=1697726562; cv=pass; d=google.com; s=arc-20160816; b=V9gQOqtgCna0e4XHj38rgQgFIUpT1npSYja/fQycw8Lt6Q2VfiYsI51d53pEEwRlUx LtpjTW4eOSyrDtSDJeG2QMHVAmmihbVCDOsoKsphpgy2tFN6Hc5KqtNN6Tjbxp5E7FEY YtN1m/5FSD50UqUH53U2SD24I3dTcvMR1jUKRQR20qJMxeBT06Ryc6nx9w/f9ZfZEfTb HrWu7TX0XzdCslaayBwyUx5MMCgVIPgVqqvkN2F6T/d115xEmJVdxR4pT1lMUYLJRJM0 QUWK6u/Q7MwlOGVoY/YOnQw2fIFTPxCPY3UlT/99MRMUhbIwfKLD0uSjBzrqsMDTMRtU CCog== ARC-Message-Signature: i=2; a=rsa-sha256; c=relaxed/relaxed; d=google.com; s=arc-20160816; h=errors-to:list-subscribe:list-help:list-post:list-archive :list-unsubscribe:list-id:precedence:content-transfer-encoding :mime-version:message-id:date:subject:cc:to:from:dkim-signature :arc-filter:dmarc-filter:delivered-to; bh=ah3XPnV9rUh2kJsQlCQ3dkutF6CGddHlbmmKy1ny/e4=; fh=YX8BRpAK3yqrBuqIriH1oUjwsfVdLQiYGwo6trMVTpo=; b=ExcPevQDO9kIjLbvYUDh/CBwvO4yaDclIAiz4WqrubtXqI+qxFUKivCc7y+qG/qQY0 AJIUo/X75DwEBgbxy16agueiC1I3mtOrFpWnxMfiYm/HuZBFomMCS2wHU3eMZjuUIYqV 4scj/4fACV0cxgZe/LrEQRm3oUEB7tLnKlG3DGKCNoXC2NhvlZZ+wjILtMRFtq1Oj2TU bI8/oRMFyLsYUdWht1PII5+UXzotZZX6zuGgtfPa00x0g964kz7PVB6gNuZXVNUdG7WX IOBkddGny/TdekJobYtyNbDe8CkWGY7DVX5zzMYYc2G9qd91otEqApv52/j27XwXVALm VlTw== ARC-Authentication-Results: i=2; mx.google.com; dkim=pass header.i=@adacore.com header.s=google header.b=IBB8AW2P; arc=pass (i=1); 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=adacore.com Received: from server2.sourceware.org (server2.sourceware.org. [2620:52:3:1:0:246e:9693:128c]) by mx.google.com with ESMTPS id el7-20020ad459c7000000b0066cf91dd0cesi1588317qvb.127.2023.10.19.07.42.42 for (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Thu, 19 Oct 2023 07:42:42 -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=@adacore.com header.s=google header.b=IBB8AW2P; arc=pass (i=1); 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=adacore.com Received: from server2.sourceware.org (localhost [IPv6:::1]) by sourceware.org (Postfix) with ESMTP id 2EAFD385DC0D for ; Thu, 19 Oct 2023 14:42:29 +0000 (GMT) X-Original-To: gcc-patches@gcc.gnu.org Delivered-To: gcc-patches@gcc.gnu.org Received: from mail-wr1-x42e.google.com (mail-wr1-x42e.google.com [IPv6:2a00:1450:4864:20::42e]) by sourceware.org (Postfix) with ESMTPS id 24359385840E for ; Thu, 19 Oct 2023 14:41:59 +0000 (GMT) DMARC-Filter: OpenDMARC Filter v1.4.2 sourceware.org 24359385840E Authentication-Results: sourceware.org; dmarc=pass (p=none dis=none) header.from=adacore.com Authentication-Results: sourceware.org; spf=pass smtp.mailfrom=adacore.com ARC-Filter: OpenARC Filter v1.0.0 sourceware.org 24359385840E Authentication-Results: server2.sourceware.org; arc=none smtp.remote-ip=2a00:1450:4864:20::42e ARC-Seal: i=1; a=rsa-sha256; d=sourceware.org; s=key; t=1697726523; cv=none; b=qeKDwkPzOiVOVXx1p6QLdpi80C4rx0y8iJIjrkWztbEAbAnTiaV90C7BTqhRZ2z2iqqro1kPj/LxdP9TmCvzB5cXRbjTC/tll+NmKFlNKvoeBIllVSigm7Zi6+3JDPQT5hZpzKF+uqd5w6YGTQnHbhqDGnPPJrDiwkcZWkn4EVw= ARC-Message-Signature: i=1; a=rsa-sha256; d=sourceware.org; s=key; t=1697726523; c=relaxed/simple; bh=QEV2ecnsYyD0e9A9k06JD8cwsyN2uG9onxITx9bPyps=; h=DKIM-Signature:From:To:Subject:Date:Message-ID:MIME-Version; b=re5RcKl5CZ2JtbBsTN8LaVF0jIwIDOKTelwtOwaH7ZtmEXldqWRwLFtBGHNxJUoQ6+3T87tF58qSJJRV7+OP+1dejRt/VneyDtt/JbzuUuDHIu5oc4W4x4bBFaIRWmkRsNpzbsDEvu8vSHPPC7Ai3YlHBRToKJM2tzn8vX9MyKI= ARC-Authentication-Results: i=1; server2.sourceware.org Received: by mail-wr1-x42e.google.com with SMTP id ffacd0b85a97d-32da4ffd7e5so549362f8f.0 for ; Thu, 19 Oct 2023 07:41:59 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=adacore.com; s=google; t=1697726519; x=1698331319; darn=gcc.gnu.org; h=content-transfer-encoding:mime-version:message-id:date:subject:cc :to:from:from:to:cc:subject:date:message-id:reply-to; bh=ah3XPnV9rUh2kJsQlCQ3dkutF6CGddHlbmmKy1ny/e4=; b=IBB8AW2PXy2p5EQNjOhco9eHoBjWek1WNtIyOAXle9xRPn6M+JfU1OcTDOrVlh7adN CUPJDY0KO0p3bXiAZXM47nGc+00i65u0u0jTuLQclS4uby34ayJVZufHmdgsf+z8yW6A P9jsqU5LRj5PNuWhFOUNuOXAeqxWXnmzh8N+u7NTug5Tpdi6OoojNWHKZIugMDrw79Lz h/BFQ7IhHrIlTdGi+Xsy+eXOlsgZSpFj/bBNJes/hWG7cUMKmK5Ms9CCd248r9OMZ8uE MuX4LzHsfV5YqPGy0+TY9yUQDlqtVqSIe52j/49ctZZlba4EBMtd5qCWAE80ctoIfSuz 0uQw== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1697726519; x=1698331319; h=content-transfer-encoding:mime-version:message-id:date:subject:cc :to:from:x-gm-message-state:from:to:cc:subject:date:message-id :reply-to; bh=ah3XPnV9rUh2kJsQlCQ3dkutF6CGddHlbmmKy1ny/e4=; b=VXzmIWxcvK2rTeAoJLgkXfSy5IF3O7DJ66rNynhVyisMNLChf2SHoCnkxxW05eeuX5 nzd64ViyUuyevvzg3cSk87nDhpoK9IP6o5gHWJJp0gaImzdCBHkbbrGRlmIaCRhOnLLL tmqviJ9NRMuSbpP98CpbDAlIOVyF30f3dkEB6aC/HVlOpglVc6VwjdrB8ODJAMWi/qF+ Jkfys60WVoUQvOPLNDLspbjBdLBtu7CjcA+6ebsjSwCWUK6u1rceeQCe0zoY976JFd0G +FLykA+yZDqu2vrgSuEqYFj4U91aodEECVEwxg13BCWvSBnIicwpcdVmasjsz0ke7V4J QLSw== X-Gm-Message-State: AOJu0YzHQFqFa2dEDfF4lXdaPem1+w3LyJVTungC85EcRd4YDIpBpBqi QX56U/t3QHw1RVmKfdOmDOy5dgs65mbrUJeZ0axbEA== X-Received: by 2002:adf:a499:0:b0:32d:a3f7:f0dd with SMTP id g25-20020adfa499000000b0032da3f7f0ddmr2074368wrb.25.1697726518533; Thu, 19 Oct 2023 07:41:58 -0700 (PDT) Received: from poulhies-Precision-5550.lan ([2001:861:3382:1a90:b43b:dc95:363f:b759]) by smtp.gmail.com with ESMTPSA id b16-20020a056000055000b00326f5d0ce0asm4672720wrf.21.2023.10.19.07.41.57 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Thu, 19 Oct 2023 07:41:58 -0700 (PDT) From: =?utf-8?q?Marc_Poulhi=C3=A8s?= To: gcc-patches@gcc.gnu.org Cc: Patrick Bernardi Subject: [COMMITTED] ada: Document gnatbind -Q switch Date: Thu, 19 Oct 2023 16:41:53 +0200 Message-ID: <20231019144156.339532-1-poulhies@adacore.com> X-Mailer: git-send-email 2.42.0 MIME-Version: 1.0 X-Spam-Status: No, score=-13.7 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 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.30 Precedence: list List-Id: Gcc-patches mailing list List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: gcc-patches-bounces+ouuuleilei=gmail.com@gcc.gnu.org X-getmail-retrieved-from-mailbox: INBOX X-GMAIL-THRID: 1780195327950369417 X-GMAIL-MSGID: 1780195327950369417 From: Patrick Bernardi Add documentation for the -Q gnatbind switch in GNAT User's Guide and improve gnatbind's help output for the switch to emphasize that it adds the requested number of stacks to the secondary stack pool generated by the binder. gcc/ada/ * bindusg.adb (Display): Make it clear -Q adds to the number of secondary stacks generated by the binder. * doc/gnat_ugn/building_executable_programs_with_gnat.rst: Document the -Q gnatbind switch and fix references to old runtimes. * gnat-style.texi: Regenerate. * gnat_rm.texi: Regenerate. * gnat_ugn.texi: Regenerate. Tested on x86_64-pc-linux-gnu, committed on master. --- gcc/ada/bindusg.adb | 2 +- ...building_executable_programs_with_gnat.rst | 29 ++++++++++--- gcc/ada/gnat-style.texi | 4 +- gcc/ada/gnat_rm.texi | 4 +- gcc/ada/gnat_ugn.texi | 41 ++++++++++++++----- 5 files changed, 59 insertions(+), 21 deletions(-) diff --git a/gcc/ada/bindusg.adb b/gcc/ada/bindusg.adb index fca425b2244..89a6caedf31 100644 --- a/gcc/ada/bindusg.adb +++ b/gcc/ada/bindusg.adb @@ -234,7 +234,7 @@ package body Bindusg is -- Line for Q switch Write_Line - (" -Qnnn Generate nnn default-sized secondary stacks"); + (" -Qnnn Generate nnn additional default-sized secondary stacks"); -- Line for -r switch 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 index 6e80163d6d4..a708ef4b995 100644 --- a/gcc/ada/doc/gnat_ugn/building_executable_programs_with_gnat.rst +++ b/gcc/ada/doc/gnat_ugn/building_executable_programs_with_gnat.rst @@ -6524,12 +6524,12 @@ be presented in subsequent sections. determines the initial size of the secondary stack for each task and the smallest amount the secondary stack can grow by. - For Ravenscar, ZFP, and Cert run-times the size of the secondary stack is - fixed. This switch can be used to change the default size of these stacks. - The default secondary stack size can be overridden on a per-task basis if - individual tasks have different secondary stack requirements. This is - achieved through the Secondary_Stack_Size aspect that takes the size of the - secondary stack in bytes. + For Light, Light-Tasking, and Embedded run-times the size of the secondary + stack is fixed. This switch can be used to change the default size of these + stacks. The default secondary stack size can be overridden on a per-task + basis if individual tasks have different secondary stack requirements. This + is achieved through the Secondary_Stack_Size aspect, which takes the size of + the secondary stack in bytes. .. index:: -e (gnatbind) @@ -6739,6 +6739,23 @@ be presented in subsequent sections. Generate binder file suitable for CodePeer. +.. index:: -Q (gnatbind) + +:switch:`-Q{nnn}` + Generate ``nnn`` additional default-sized secondary stacks. + + Tasks declared at the library level that use default-size secondary stacks + have their secondary stacks allocated from a pool of stacks generated by + gnatbind. This allows the default secondary stack size to be quickly changed + by rebinding the application. + + While the binder sizes this pool to match the number of such tasks defined in + the application, the pool size may need to be increased with the :switch:`-Q` + switch to accommodate foreign threads registered with the Light run-time. For + more information, please see the *The Primary and Secondary Stack* chapter in + the *GNAT User’s Guide Supplement for Cross Platforms*. + + .. index:: -R (gnatbind) :switch:`-R` diff --git a/gcc/ada/gnat-style.texi b/gcc/ada/gnat-style.texi index 5555bcdc160..33bb1886985 100644 --- a/gcc/ada/gnat-style.texi +++ b/gcc/ada/gnat-style.texi @@ -3,7 +3,7 @@ @setfilename gnat-style.info @documentencoding UTF-8 @ifinfo -@*Generated by Sphinx 5.2.3.@* +@*Generated by Sphinx 7.2.6.@* @end ifinfo @settitle GNAT Coding Style A Guide for GNAT Developers @defindex ge @@ -19,7 +19,7 @@ @copying @quotation -GNAT Coding Style: A Guide for GNAT Developers , May 09, 2023 +GNAT Coding Style: A Guide for GNAT Developers , Oct 16, 2023 AdaCore diff --git a/gcc/ada/gnat_rm.texi b/gcc/ada/gnat_rm.texi index b7e098331e9..9a6a0170ae8 100644 --- a/gcc/ada/gnat_rm.texi +++ b/gcc/ada/gnat_rm.texi @@ -3,7 +3,7 @@ @setfilename gnat_rm.info @documentencoding UTF-8 @ifinfo -@*Generated by Sphinx 5.2.3.@* +@*Generated by Sphinx 7.2.6.@* @end ifinfo @settitle GNAT Reference Manual @defindex ge @@ -19,7 +19,7 @@ @copying @quotation -GNAT Reference Manual , Jul 17, 2023 +GNAT Reference Manual , Oct 16, 2023 AdaCore diff --git a/gcc/ada/gnat_ugn.texi b/gcc/ada/gnat_ugn.texi index 1562bee1f64..897153bcfc7 100644 --- a/gcc/ada/gnat_ugn.texi +++ b/gcc/ada/gnat_ugn.texi @@ -3,7 +3,7 @@ @setfilename gnat_ugn.info @documentencoding UTF-8 @ifinfo -@*Generated by Sphinx 5.2.3.@* +@*Generated by Sphinx 7.2.6.@* @end ifinfo @settitle GNAT User's Guide for Native Platforms @defindex ge @@ -19,7 +19,7 @@ @copying @quotation -GNAT User's Guide for Native Platforms , Sep 26, 2023 +GNAT User's Guide for Native Platforms , Oct 16, 2023 AdaCore @@ -15781,12 +15781,12 @@ a chain of blocks in the heap. In this case, the default secondary stack size determines the initial size of the secondary stack for each task and the smallest amount the secondary stack can grow by. -For Ravenscar, ZFP, and Cert run-times the size of the secondary stack is -fixed. This switch can be used to change the default size of these stacks. -The default secondary stack size can be overridden on a per-task basis if -individual tasks have different secondary stack requirements. This is -achieved through the Secondary_Stack_Size aspect that takes the size of the -secondary stack in bytes. +For Light, Light-Tasking, and Embedded run-times the size of the secondary +stack is fixed. This switch can be used to change the default size of these +stacks. The default secondary stack size can be overridden on a per-task +basis if individual tasks have different secondary stack requirements. This +is achieved through the Secondary_Stack_Size aspect, which takes the size of +the secondary stack in bytes. @end table @geindex -e (gnatbind) @@ -16047,6 +16047,27 @@ Pessimistic (worst-case) elaboration order. @item @code{-P} Generate binder file suitable for CodePeer. +@end table + +@geindex -Q (gnatbind) + + +@table @asis + +@item @code{-Q`nnn'} + +Generate @code{nnn} additional default-sized secondary stacks. + +Tasks declared at the library level that use default-size secondary stacks +have their secondary stacks allocated from a pool of stacks generated by +gnatbind. This allows the default secondary stack size to be quickly changed +by rebinding the application. + +While the binder sizes this pool to match the number of such tasks defined in +the application, the pool size may need to be increased with the @code{-Q} +switch to accommodate foreign threads registered with the Light run-time. For +more information, please see the `The Primary and Secondary Stack' chapter in +the `GNAT User’s Guide Supplement for Cross Platforms'. @geindex -R (gnatbind) @@ -22827,13 +22848,13 @@ Alternatively, you can specify @code{rts-sjlj/adainclude} in the file Selecting another run-time library temporarily can be achieved by using the @code{--RTS} switch, e.g., @code{--RTS=sjlj} -@anchor{gnat_ugn/platform_specific_information choosing-the-scheduling-policy}@anchor{1bb} + @geindex SCHED_FIFO scheduling policy @geindex SCHED_RR scheduling policy @geindex SCHED_OTHER scheduling policy - +@anchor{gnat_ugn/platform_specific_information choosing-the-scheduling-policy}@anchor{1bb} @menu * Choosing the Scheduling Policy::