Index: llvm/docs/Passes.rst
===================================================================
--- llvm/docs/Passes.rst
+++ llvm/docs/Passes.rst
@@ -355,6 +355,16 @@
 ``ScalarEvolution`` has a more complete understanding of pointer arithmetic
 than ``BasicAliasAnalysis``' collection of ad-hoc analyses.
 
+``-stack-safety``: Stack Safety Analysis
+------------------------------------------------
+
+The ``StackSafety`` analysis can be used to determine if stack allocated
+variables can be considered safe from memory access bugs. The pass attaches
+``!stack-safe`` to such variables.
+
+This analysis primary purpose it be used by sanitizers to avoid unnecessary
+instrumentation of safe variables.
+
 ``-targetdata``: Target Data Layout
 -----------------------------------
 
Index: llvm/docs/StackSafetyAnalysis.rst
===================================================================
--- /dev/null
+++ llvm/docs/StackSafetyAnalysis.rst
@@ -0,0 +1,68 @@
+==================================
+Stack Safety Analysis
+==================================
+
+
+Introduction
+============
+
+The Stack Safety Analysis is the pass which determines if stack allocated
+variables can be considered ‘safe’ from memory access bugs.
+
+'safe' variable can be defined as a variable without possibility of buffer
+underflow, overflow, or use-after-return. In future it can be extended to track
+other variable properties.
+
+The primary purpose of the analysis is to be used by sanitizers to avoid
+unnecessary instrumentation of safe variables. SafeStack is going to be the
+first user.
+
+How to use
+==========
+
+User of the analysis should add StackSafetyGlobalAnalysis as dependency and then
+check ``!stack-safe`` in allocas metadata.
+TODO: (See ``lib/CodeGen/SafeStack.cpp`` for the usage example.)
+
+How it works
+============
+
+Analysis implemented in two stages.
+
+'local' stage performs Depth-first search inside functions to collect all uses
+of each alloca and function's argument inside the function. After this stage we
+know which parts of allocas are used by functions itself but we don’t know what
+happened after it passed as argument into a function call. So we need another
+stage called as 'global'.
+
+The global stage also does Depth-first search on function calls inside a single
+module and propagates allocas usage through functions calls.
+
+In case of ThinLTO it does global stage on Module Summary Index.
+
+After the global stage we add ``!stack-safe`` into metadata of all allocas where
+access is proven to be constrained by alloca's boundaries.  
+
+Testing
+=======
+
+The analysis covered with lit tests.
+
+We expect that users can tolerate false classification variable as
+'unsafe' when in-fact it's 'safe'. This may lead to inefficient code. However we
+can’t accept false 'safe' classification which may cause sanitizers miss actual
+bugs in instrumented code. To avoid that we want additional validation tool.
+
+AddressSanitizer may help with this validation. We can instrument all variables
+as usual but additionally store ``!stack-safe`` in 
+``ASanStackVariableDescription``. Then if AddressSanitizer will detect a bug on
+a 'safe' variable we will produce additional report to let user know that
+probably Stack Safety Analysis failed and we should check for a bug in the
+compiler.
+
+Benchmarks
+==========
+
+TODO
+
+
Index: llvm/docs/index.rst
===================================================================
--- llvm/docs/index.rst
+++ llvm/docs/index.rst
@@ -298,6 +298,7 @@
    PDB/index
    CFIVerify
    SpeculativeLoadHardening
+   StackSafetyAnalysis
 
 :doc:`WritingAnLLVMPass`
    Information on how to write LLVM transformations and analyses.
@@ -434,6 +435,9 @@
 :doc:`SpeculativeLoadHardening`
   A description of the Speculative Load Hardening mitigation for Spectre v1.
 
+:doc:`StackSafetyAnalysis`
+  This document describes design of stack safety analysis of local variables.
+
 Development Process Documentation
 =================================