Index: flang/docs/fstack-arrays.md
===================================================================
--- /dev/null
+++ flang/docs/fstack-arrays.md
@@ -0,0 +1,45 @@
+# -fstack-arrays
+Other Fortran compilers have options to ensure that arrays are allocated on the
+stack. These options are enabled along with `-Ofast`.
+
+Flang allocates most arrays on the stack by default, but there are a few cases
+where temporary arrays are allocated on the heap:
+- `flang/lib/Optimizer/Transforms/ArrayValueCopy.cpp`
+- `flang/lib/Optimizer/Transforms/MemoryAllocation.cpp`
+- `flang/lib/Lower/ConvertExpr.cpp`
+- `flang/lib/Lower/IntrinsicCall.cpp`
+- `flang/lib/Lower/ConvertVariable.cpp`
+
+## `ArrayValueCopy.cpp`
+Memory is allocated for a temporary array in `allocateArrayTemp()`. This should
+be changed so that if an option is set requesting stack arrays,
+`allocateArrayTemp()` will generate `fir.alloca` instead of `fir.allocmem` and
+the clean up code will not include a `fir.freemem`. The `fir.alloca` needs to be
+placed in the function entry block so that array value copy operations inside a
+loop do not lead to repeated large stack allocations.
+
+## `MemoryAllocation.cpp`
+The default options for the Memory Allocation transformation ensure that no
+array allocations, no matter how large, are moved from the stack to the heap.
+
+## `ConvertExpr.cpp`
+`ConvertExpr.cpp` allocates many array temporaries on the heap:
+  - Lowering mask expressions
+  - Passing array arguments by value or when they need re-shaping
+  - Lowering elemental array expressions
+  - Array initialization
+
+These will need addressing individually. The details are TODO.
+
+## `IntrinsicCall.cpp`
+The existing design is for the runtime to do the allocation and the lowering
+code to insert `fir.freemem` to remove the allocation. It is not clear whether
+this can be replaced by adapting lowering code to do stack allocations and to
+pass these to the runtime. This would be a significant change and so is out of
+scope of `-fstack-arrays`.
+
+## `ConvertVariable.cpp`
+Sometimes heap allocations are used, but only when stack allocations are not
+possible. The code documentation says that most of these should be cleaned up
+in later stages and not lead to generated code. These allocations will be out of
+scope for `-fstack-arrays`.