diff --git a/flang/docs/FAQ.md b/flang/docs/FAQ.md new file mode 100644 index 0000000000000..0b0b6ebdacf0b --- /dev/null +++ b/flang/docs/FAQ.md @@ -0,0 +1,52 @@ + + +# 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. + +An internal procedure has a "host scope", which is the scope in which it is contained. +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 the 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 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. + +```{note} +The trampoline code generated by Flang is not itself a security risk. +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. + +```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) +$ flang src.f90 -fuse-ld=lld -Wl,-z,execstack +``` diff --git a/flang/docs/FortranStandardsSupport.md b/flang/docs/FortranStandardsSupport.md index dc273fb920e04..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 [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. 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