[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)).
----------------
DavidSpickett wrote:

That's an improvement but I would change it more to get the key messages across:
* Executable stacks have risks
* We're not going to enumerate them here
* Do your own research

Side note: We can drop the "however", I think that was linked to a sentence that's now removed.

So in my best corporate product manual style:
"An executable stack increases the risk and impact of certain classes of security vulnerability, such as stack buffer overflows. You should determine whether these risks are appropriate for your software."

If you have a really good, really specific article from someone reputable (GCC docs, redhat, that sort of place) then we could link that but otherwise I think we just say that there is a risk and leave it at that.

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