[flang-commits] [flang] [flang][docs] Add an FAQ about an executable stack (PR #171241)

[David Spickett via flang-commits]

================
@@ -0,0 +1,54 @@
+<!--===- 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 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 (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 (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}
+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.
----------------
DavidSpickett wrote:

Caveat: this is quite a niche comment, and is very much an improvement on text that is already fine. If these are the kind of comments I'm leaving, take that as a sign you are writing well.

I suggest a rewording to make this easier to read:
The risk comes from the possibility of executing malicious code that an attacker has placed on the stack.

When reading this version, I get all the information as I need it, rather than having to buffer the first part of the sentence to make sense of the last part. "that is injected into the program" is a side quest so to speak.

Apparently what I'm suggesting is a "right-branching restrictive relative clause".  My "side quest" is a "center embedded clause". Literally learned that term right now :)

The "center-embedded" clause that you have used is not wrong in itself. I just think in factual informative documents, the simpler the form, the better. It's often hard to spot it as the author of a document, so that's what reviewers are for.

https://github.com/llvm/llvm-project/pull/171241