[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
Fri Dec 12 00:41:58 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 1/8] [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 2/8] 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 3/8] 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 4/8] 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 5/8] 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 6/8] 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 7/8] 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 8/8] 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
More information about the flang-commits
mailing list