[flang-commits] [flang] [flang][docs] Add an FAQ about an executable stack (PR #171241)
Yusuke MINATO via flang-commits
flang-commits at lists.llvm.org
Mon Dec 15 16:57:35 PST 2025
https://github.com/yus3710-fj updated https://github.com/llvm/llvm-project/pull/171241
>From 22fe0ef4e9334cf487744800b269d077aeaa2ccd Mon Sep 17 00:00:00 2001
From: Yusuke MINATO <minato.yusuke at fujitsu.com>
Date: Fri, 5 Dec 2025 12:03:05 +0900
Subject: [PATCH 01/11] [flang][docs] Add an FAQ about an executable stack
---
flang/docs/FAQ.md | 47 +++++++++++++++++++++++++++
flang/docs/FortranStandardsSupport.md | 2 +-
2 files changed, 48 insertions(+), 1 deletion(-)
create mode 100644 flang/docs/FAQ.md
diff --git a/flang/docs/FAQ.md b/flang/docs/FAQ.md
new file mode 100644
index 0000000000000..d7e56cc12b518
--- /dev/null
+++ b/flang/docs/FAQ.md
@@ -0,0 +1,47 @@
+<!--===- docs/FAQ.md
+
+ Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
+ See https://llvm.org/LICENSE.txt for license information.
+ SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
+
+-->
+
+<!-- TODO: remove this after adding this page to ToC -->
+```{eval-rst}
+:orphan:
+```
+
+# Frequently Asked Questions (FAQ)
+
+```{contents}
+---
+local:
+---
+```
+
+## Driver
+
+### Why do I get a warning or error about an executable stack?
+
+This warning or error occurs because Flang's implementation of pointers to internal procedures requires an executable stack.
+
+When an internal procedure is referenced from outside its host scope (e.g., via a procedure pointer), the implementation must ensure it can still access its host-associated variables.
+To achieve this, the current implementation of Flang generates a small piece of code, called a "trampoline", on the stack dynamically.
+Since this trampoline code must be executed, the stack needs to be executable.
+For a more detailed explanation of trampolines, please refer to the [design document](InternalProcedureTrampolines.md).
+
+However, an executable stack can introduce security vulnerabilities (e.g., by enabling [buffer overflow attacks](https://en.wikipedia.org/wiki/Buffer_overflow#Stack-based_exploitation)).
+For this reason, modern linkers often issue a warning or error.
+In particular, the LLVM Linker (`lld`) never enables an executable stack unless you explicitly allow it.
+
+> NOTE: The trampoline code generated by Flang is not itself a security risk.
+> The risk comes from the possibility that other malicious code, if present in the program or its libraries, could be executed from the stack.
+
+When you use the Flang driver (i.e., the `flang` command) to generate executables, you can instruct the linker to enable an executable stack with the `-Wl,-z,execstack` or `-Xlinker -zexecstack` flag.
+
+```console
+$ flang src.f90 -fuse-ld=lld
+ld.lld: error: src.o: requires an executable stack, but -z execstack is not specified
+flang-22: error: linker command failed with exit code 1 (use -v to see invocation)
+$ flang src.f90 -fuse-ld=lld -Wl,-z,execstack
+```
diff --git a/flang/docs/FortranStandardsSupport.md b/flang/docs/FortranStandardsSupport.md
index dc273fb920e04..d375e3b45d451 100644
--- a/flang/docs/FortranStandardsSupport.md
+++ b/flang/docs/FortranStandardsSupport.md
@@ -95,7 +95,7 @@ All features except those listed in the following table are supported.
|------------------------------------------------------------|--------|---------------------------------------------------------|
| Coarrays | N | Lowering and runtime support is not implemented |
| do concurrent | P | Sequential execution works. Parallel support in progress|
-| Internal procedure as an actual argument or pointer target | Y | Current implementation requires stack to be executable. See [Proposal](InternalProcedureTrampolines.md) |
+| Internal procedure as an actual argument or pointer target | Y | Current implementation requires stack to be executable. See [FAQ](FAQ.md#why-do-i-get-a-warning-or-error-about-an-executable-stack) and [Proposal](InternalProcedureTrampolines.md) |
## Fortran 2003
All features except those listed in the following table are supported.
>From c33c549bc72ccd584cf398714c4e5a420844d01d Mon Sep 17 00:00:00 2001
From: Yusuke MINATO <minato.yusuke at fujitsu.com>
Date: Wed, 10 Dec 2025 11:15:25 +0900
Subject: [PATCH 02/11] Use the `{note}` admonition
Co-authored-by: Tarun Prabhu <tarunprabhu at gmail.com>
---
flang/docs/FAQ.md | 5 ++++-
1 file changed, 4 insertions(+), 1 deletion(-)
diff --git a/flang/docs/FAQ.md b/flang/docs/FAQ.md
index d7e56cc12b518..8497e6c002629 100644
--- a/flang/docs/FAQ.md
+++ b/flang/docs/FAQ.md
@@ -35,7 +35,10 @@ For this reason, modern linkers often issue a warning or error.
In particular, the LLVM Linker (`lld`) never enables an executable stack unless you explicitly allow it.
> NOTE: The trampoline code generated by Flang is not itself a security risk.
-> The risk comes from the possibility that other malicious code, if present in the program or its libraries, could be executed from the stack.
+```{note}
+The trampoline code generated by Flang is not itself a security risk.
+The risk comes from the possibility that other malicious code, if present in the program or its libraries, could be executed from the stack.
+```
When you use the Flang driver (i.e., the `flang` command) to generate executables, you can instruct the linker to enable an executable stack with the `-Wl,-z,execstack` or `-Xlinker -zexecstack` flag.
>From 5ed88c65809314d406aac3a68de29a76774e5130 Mon Sep 17 00:00:00 2001
From: Yusuke MINATO <minato.yusuke at fujitsu.com>
Date: Wed, 10 Dec 2025 11:17:07 +0900
Subject: [PATCH 03/11] Simpify the phrasing
Co-authored-by: Tarun Prabhu <tarunprabhu at gmail.com>
---
flang/docs/FAQ.md | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/flang/docs/FAQ.md b/flang/docs/FAQ.md
index 8497e6c002629..f03f481570969 100644
--- a/flang/docs/FAQ.md
+++ b/flang/docs/FAQ.md
@@ -23,7 +23,7 @@ local:
### Why do I get a warning or error about an executable stack?
-This warning or error occurs because Flang's implementation of pointers to internal procedures requires an executable stack.
+This occurs because Flang's implementation of pointers to internal procedures requires an executable stack.
When an internal procedure is referenced from outside its host scope (e.g., via a procedure pointer), the implementation must ensure it can still access its host-associated variables.
To achieve this, the current implementation of Flang generates a small piece of code, called a "trampoline", on the stack dynamically.
>From 509beb0231ffe0d167a38a2efe8c7f834496fe3c Mon Sep 17 00:00:00 2001
From: Yusuke MINATO <minato.yusuke at fujitsu.com>
Date: Wed, 10 Dec 2025 11:20:17 +0900
Subject: [PATCH 04/11] Add missing "that"
Co-authored-by: Tarun Prabhu <tarunprabhu at gmail.com>
---
flang/docs/FAQ.md | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/flang/docs/FAQ.md b/flang/docs/FAQ.md
index f03f481570969..2eb9a12545e48 100644
--- a/flang/docs/FAQ.md
+++ b/flang/docs/FAQ.md
@@ -25,7 +25,7 @@ local:
This occurs because Flang's implementation of pointers to internal procedures requires an executable stack.
-When an internal procedure is referenced from outside its host scope (e.g., via a procedure pointer), the implementation must ensure it can still access its host-associated variables.
+When an internal procedure is referenced from outside its host scope (e.g., via a procedure pointer), the implementation must ensure that it can still access its host-associated variables.
To achieve this, the current implementation of Flang generates a small piece of code, called a "trampoline", on the stack dynamically.
Since this trampoline code must be executed, the stack needs to be executable.
For a more detailed explanation of trampolines, please refer to the [design document](InternalProcedureTrampolines.md).
>From 4cab3616e507b0770add0bee1d83bde378babc86 Mon Sep 17 00:00:00 2001
From: Yusuke MINATO <minato.yusuke at fujitsu.com>
Date: Wed, 10 Dec 2025 15:14:11 +0900
Subject: [PATCH 05/11] Address comments
---
flang/docs/FAQ.md | 11 +++++++----
1 file changed, 7 insertions(+), 4 deletions(-)
diff --git a/flang/docs/FAQ.md b/flang/docs/FAQ.md
index 2eb9a12545e48..fdf9b420d5a21 100644
--- a/flang/docs/FAQ.md
+++ b/flang/docs/FAQ.md
@@ -31,18 +31,21 @@ Since this trampoline code must be executed, the stack needs to be executable.
For a more detailed explanation of trampolines, please refer to the [design document](InternalProcedureTrampolines.md).
However, an executable stack can introduce security vulnerabilities (e.g., by enabling [buffer overflow attacks](https://en.wikipedia.org/wiki/Buffer_overflow#Stack-based_exploitation)).
-For this reason, modern linkers often issue a warning or error.
-In particular, the LLVM Linker (`lld`) never enables an executable stack unless you explicitly allow it.
+Therefore, modern linkers often issue a warning or error if an executable stack is not explicitly allowed.
+For instance, the GNU Linker (`ld`) issues a warning while the LLVM Linker (`lld`) emits an error.
-> NOTE: The trampoline code generated by Flang is not itself a security risk.
```{note}
The trampoline code generated by Flang is not itself a security risk.
-The risk comes from the possibility that other malicious code, if present in the program or its libraries, could be executed from the stack.
+The risk comes from the possibility of executing malicious code, that is injected into the program, from the stack.
```
When you use the Flang driver (i.e., the `flang` command) to generate executables, you can instruct the linker to enable an executable stack with the `-Wl,-z,execstack` or `-Xlinker -zexecstack` flag.
```console
+$ flang src.f90 -fuse-ld=ld
+/path/to/ld: warning: src.o: requires executable stack (because the .note.GNU-stack section is executable)
+$ flang src.f90 -fuse-ld=ld -Wl,-z,execstack
+
$ flang src.f90 -fuse-ld=lld
ld.lld: error: src.o: requires an executable stack, but -z execstack is not specified
flang-22: error: linker command failed with exit code 1 (use -v to see invocation)
>From 7e480a1a05baf7910cea673dbb292002564e89e3 Mon Sep 17 00:00:00 2001
From: Yusuke MINATO <minato.yusuke at fujitsu.com>
Date: Thu, 11 Dec 2025 11:43:41 +0900
Subject: [PATCH 06/11] Address comments from David
---
flang/docs/FAQ.md | 15 ++++++++-------
flang/docs/FortranStandardsSupport.md | 2 +-
2 files changed, 9 insertions(+), 8 deletions(-)
diff --git a/flang/docs/FAQ.md b/flang/docs/FAQ.md
index fdf9b420d5a21..69eac4e02433f 100644
--- a/flang/docs/FAQ.md
+++ b/flang/docs/FAQ.md
@@ -21,17 +21,18 @@ local:
## Driver
-### Why do I get a warning or error about an executable stack?
+### Why do I get a warning or an error about an executable stack?
This occurs because Flang's implementation of pointers to internal procedures requires an executable stack.
-When an internal procedure is referenced from outside its host scope (e.g., via a procedure pointer), the implementation must ensure that it can still access its host-associated variables.
-To achieve this, the current implementation of Flang generates a small piece of code, called a "trampoline", on the stack dynamically.
-Since this trampoline code must be executed, the stack needs to be executable.
+When an internal procedure is referenced from outside its host scope (for example, via a procedure pointer), the implementation must ensure that it can still access variables from that host scope.
+To achieve this, the current implementation of Flang generates a small piece of code, called a "trampoline", on the stack.
+When the procedure is called, execution first goes through this trampoline.
+This means that the stack must be executable.
For a more detailed explanation of trampolines, please refer to the [design document](InternalProcedureTrampolines.md).
-However, an executable stack can introduce security vulnerabilities (e.g., by enabling [buffer overflow attacks](https://en.wikipedia.org/wiki/Buffer_overflow#Stack-based_exploitation)).
-Therefore, modern linkers often issue a warning or error if an executable stack is not explicitly allowed.
+However, an executable stack can introduce security vulnerabilities (for example, by increasing the impact of [stack buffer overflow attacks](https://en.wikipedia.org/wiki/Buffer_overflow#Stack-based_exploitation)).
+Therefore, modern linkers often issue a warning or an error if an executable stack is not explicitly requested by the developer.
For instance, the GNU Linker (`ld`) issues a warning while the LLVM Linker (`lld`) emits an error.
```{note}
@@ -39,7 +40,7 @@ The trampoline code generated by Flang is not itself a security risk.
The risk comes from the possibility of executing malicious code, that is injected into the program, from the stack.
```
-When you use the Flang driver (i.e., the `flang` command) to generate executables, you can instruct the linker to enable an executable stack with the `-Wl,-z,execstack` or `-Xlinker -zexecstack` flag.
+When you use the Flang driver (the `flang` command) to generate executables, you can instruct the linker to enable an executable stack with the `-Wl,-z,execstack` or `-Xlinker -zexecstack` flag.
```console
$ flang src.f90 -fuse-ld=ld
diff --git a/flang/docs/FortranStandardsSupport.md b/flang/docs/FortranStandardsSupport.md
index d375e3b45d451..97363dbd048a3 100644
--- a/flang/docs/FortranStandardsSupport.md
+++ b/flang/docs/FortranStandardsSupport.md
@@ -95,7 +95,7 @@ All features except those listed in the following table are supported.
|------------------------------------------------------------|--------|---------------------------------------------------------|
| Coarrays | N | Lowering and runtime support is not implemented |
| do concurrent | P | Sequential execution works. Parallel support in progress|
-| Internal procedure as an actual argument or pointer target | Y | Current implementation requires stack to be executable. See [FAQ](FAQ.md#why-do-i-get-a-warning-or-error-about-an-executable-stack) and [Proposal](InternalProcedureTrampolines.md) |
+| Internal procedure as an actual argument or pointer target | Y | Current implementation requires stack to be executable. See [FAQ](FAQ.md#why-do-i-get-a-warning-or-an-error-about-an-executable-stack) and [Proposal](InternalProcedureTrampolines.md) |
## Fortran 2003
All features except those listed in the following table are supported.
>From 66b207e7a380e94153bcd25e68eafab40aac426f Mon Sep 17 00:00:00 2001
From: Yusuke MINATO <minato.yusuke at fujitsu.com>
Date: Fri, 12 Dec 2025 17:05:09 +0900
Subject: [PATCH 07/11] Address additional comments
Co-authored-by: David Spickett <david.spickett at linaro.org>
---
flang/docs/FAQ.md | 9 +++++----
1 file changed, 5 insertions(+), 4 deletions(-)
diff --git a/flang/docs/FAQ.md b/flang/docs/FAQ.md
index 69eac4e02433f..dff71abfe2c71 100644
--- a/flang/docs/FAQ.md
+++ b/flang/docs/FAQ.md
@@ -27,17 +27,18 @@ This occurs because Flang's implementation of pointers to internal procedures re
When an internal procedure is referenced from outside its host scope (for example, via a procedure pointer), the implementation must ensure that it can still access variables from that host scope.
To achieve this, the current implementation of Flang generates a small piece of code, called a "trampoline", on the stack.
-When the procedure is called, execution first goes through this trampoline.
-This means that the stack must be executable.
+When the procedure is called, this trampoline is executed.
+The trampoline is on the stack, so the stack itself must be executable.
For a more detailed explanation of trampolines, please refer to the [design document](InternalProcedureTrampolines.md).
-However, an executable stack can introduce security vulnerabilities (for example, by increasing the impact of [stack buffer overflow attacks](https://en.wikipedia.org/wiki/Buffer_overflow#Stack-based_exploitation)).
+An executable stack increases the risk and impact of certain classes of security vulnerability, such as [stack buffer overflows](https://llsoftsec.github.io/llsoftsecbook/#stack-buffer-overflows).
Therefore, modern linkers often issue a warning or an error if an executable stack is not explicitly requested by the developer.
For instance, the GNU Linker (`ld`) issues a warning while the LLVM Linker (`lld`) emits an error.
```{note}
The trampoline code generated by Flang is not itself a security risk.
-The risk comes from the possibility of executing malicious code, that is injected into the program, from the stack.
+The risk comes from the possibility of executing malicious code that an attacker has placed on the stack.
+You should determine whether such risks are appropriate for your software.
```
When you use the Flang driver (the `flang` command) to generate executables, you can instruct the linker to enable an executable stack with the `-Wl,-z,execstack` or `-Xlinker -zexecstack` flag.
>From 29ab21158eab46f002dcd463f7f453f33bcdbdea Mon Sep 17 00:00:00 2001
From: Yusuke MINATO <minato.yusuke at fujitsu.com>
Date: Fri, 12 Dec 2025 17:40:32 +0900
Subject: [PATCH 08/11] Add this page to ToC and remove TODO
---
flang/docs/FAQ.md | 5 -----
flang/docs/index.md | 1 +
2 files changed, 1 insertion(+), 5 deletions(-)
diff --git a/flang/docs/FAQ.md b/flang/docs/FAQ.md
index dff71abfe2c71..acd20c3b6f5df 100644
--- a/flang/docs/FAQ.md
+++ b/flang/docs/FAQ.md
@@ -6,11 +6,6 @@
-->
-<!-- TODO: remove this after adding this page to ToC -->
-```{eval-rst}
-:orphan:
-```
-
# Frequently Asked Questions (FAQ)
```{contents}
diff --git a/flang/docs/index.md b/flang/docs/index.md
index 0d29c22814e99..2c07f1004a215 100644
--- a/flang/docs/index.md
+++ b/flang/docs/index.md
@@ -30,6 +30,7 @@ on how to get in touch with us and to learn more about the current status.
OpenMPSupport
Real16MathSupport
Unsigned
+ FAQ
```
# Contributing to Flang
>From 02fdc248f2d81c13749003c8a1af9a33b8e49e26 Mon Sep 17 00:00:00 2001
From: Yusuke MINATO <minato.yusuke at fujitsu.com>
Date: Mon, 15 Dec 2025 15:18:57 +0900
Subject: [PATCH 09/11] Add the definition of "host"
---
flang/docs/FAQ.md | 4 +++-
1 file changed, 3 insertions(+), 1 deletion(-)
diff --git a/flang/docs/FAQ.md b/flang/docs/FAQ.md
index acd20c3b6f5df..4d3720f9b5064 100644
--- a/flang/docs/FAQ.md
+++ b/flang/docs/FAQ.md
@@ -20,13 +20,15 @@ local:
This occurs because Flang's implementation of pointers to internal procedures requires an executable stack.
+An internal procedure has a "host scope", which is the scope surrounding it.
+It can access variables in the host scope.
When an internal procedure is referenced from outside its host scope (for example, via a procedure pointer), the implementation must ensure that it can still access variables from that host scope.
To achieve this, the current implementation of Flang generates a small piece of code, called a "trampoline", on the stack.
When the procedure is called, this trampoline is executed.
The trampoline is on the stack, so the stack itself must be executable.
For a more detailed explanation of trampolines, please refer to the [design document](InternalProcedureTrampolines.md).
-An executable stack increases the risk and impact of certain classes of security vulnerability, such as [stack buffer overflows](https://llsoftsec.github.io/llsoftsecbook/#stack-buffer-overflows).
+An executable stack increases the risk and impact of certain classes of security vulnerabilities, such as [stack buffer overflows](https://llsoftsec.github.io/llsoftsecbook/#stack-buffer-overflows).
Therefore, modern linkers often issue a warning or an error if an executable stack is not explicitly requested by the developer.
For instance, the GNU Linker (`ld`) issues a warning while the LLVM Linker (`lld`) emits an error.
>From 773ce9564b3749a5765b06f5b7bdb1bdca0ccf86 Mon Sep 17 00:00:00 2001
From: Yusuke MINATO <minato.yusuke at fujitsu.com>
Date: Tue, 16 Dec 2025 09:57:04 +0900
Subject: [PATCH 10/11] Update flang/docs/FAQ.md
Co-authored-by: Tarun Prabhu <tarunprabhu at gmail.com>
---
flang/docs/FAQ.md | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/flang/docs/FAQ.md b/flang/docs/FAQ.md
index 4d3720f9b5064..5622e6b7a4b97 100644
--- a/flang/docs/FAQ.md
+++ b/flang/docs/FAQ.md
@@ -20,7 +20,7 @@ local:
This occurs because Flang's implementation of pointers to internal procedures requires an executable stack.
-An internal procedure has a "host scope", which is the scope surrounding it.
+An internal procedure has a "host scope", which is the scope in which it is contained.
It can access variables in the host scope.
When an internal procedure is referenced from outside its host scope (for example, via a procedure pointer), the implementation must ensure that it can still access variables from that host scope.
To achieve this, the current implementation of Flang generates a small piece of code, called a "trampoline", on the stack.
>From 124b62e248de319395d789be09eb53d4228b7686 Mon Sep 17 00:00:00 2001
From: Yusuke MINATO <minato.yusuke at fujitsu.com>
Date: Tue, 16 Dec 2025 09:57:22 +0900
Subject: [PATCH 11/11] Update flang/docs/FAQ.md
Co-authored-by: Tarun Prabhu <tarunprabhu at gmail.com>
---
flang/docs/FAQ.md | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/flang/docs/FAQ.md b/flang/docs/FAQ.md
index 5622e6b7a4b97..bc5f77b2e0d3a 100644
--- a/flang/docs/FAQ.md
+++ b/flang/docs/FAQ.md
@@ -21,7 +21,7 @@ local:
This occurs because Flang's implementation of pointers to internal procedures requires an executable stack.
An internal procedure has a "host scope", which is the scope in which it is contained.
-It can access variables in the host scope.
+It can access variables defined in that host scope.
When an internal procedure is referenced from outside its host scope (for example, via a procedure pointer), the implementation must ensure that it can still access variables from that host scope.
To achieve this, the current implementation of Flang generates a small piece of code, called a "trampoline", on the stack.
When the procedure is called, this trampoline is executed.
More information about the flang-commits
mailing list