From d3130529044a59b9abfcd6fe651ac119316d0f55 Mon Sep 17 00:00:00 2001 From: Vitaly Buka Date: Mon, 26 Nov 2018 23:16:07 +0000 Subject: [PATCH] [stack-safety] Analysis documentation Summary: Basic documentation of the Stack Safety Analysis. It will be improved during review and upstream of an implementation. Reviewers: kcc, eugenis, vlad.tsyrklevich, glider Reviewed By: vlad.tsyrklevich Subscribers: arphaman, llvm-commits Differential Revision: https://reviews.llvm.org/D53336 llvm-svn: 347612 --- llvm/docs/Passes.rst | 9 +++++ llvm/docs/StackSafetyAnalysis.rst | 57 +++++++++++++++++++++++++++++++ llvm/docs/index.rst | 5 +++ 3 files changed, 71 insertions(+) create mode 100644 llvm/docs/StackSafetyAnalysis.rst diff --git a/llvm/docs/Passes.rst b/llvm/docs/Passes.rst index 9ab214984d2d..9a1b41762ed2 100644 --- a/llvm/docs/Passes.rst +++ b/llvm/docs/Passes.rst @@ -355,6 +355,15 @@ between different iterations. ``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. + +This analysis' primary purpose is to be used by sanitizers to avoid unnecessary +instrumentation of safe variables. + ``-targetdata``: Target Data Layout ----------------------------------- diff --git a/llvm/docs/StackSafetyAnalysis.rst b/llvm/docs/StackSafetyAnalysis.rst new file mode 100644 index 000000000000..07112dc7ca4c --- /dev/null +++ b/llvm/docs/StackSafetyAnalysis.rst @@ -0,0 +1,57 @@ +================================== +Stack Safety Analysis +================================== + + +Introduction +============ + +The Stack Safety Analysis determines if stack allocated variables can be +considered 'safe' from memory access bugs. + +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. + +'safe' variables can be defined as variables that can not be used out-of-scope +(e.g. use-after-return) or accessed out of bounds. In the future it can be +extended to track other variable properties. E.g. we plan to extend +implementation with a check to make sure that variable is always initialized +before every read to optimize use-of-uninitialized-memory checks. + +How it works +============ + +The analysis is implemented in two stages: + +The intra-procedural, or 'local', stage performs a depth-first search inside +functions to collect all uses of each alloca, including loads/stores and uses as +arguments functions. After this stage we know which parts of the alloca are used +by functions itself but we don't know what happens after it is passed as +an argument to another function. + +The inter-procedural, or 'global', stage, resolves what happens to allocas after +they are passed as function arguments. This stage performs a depth-first search +on function calls inside a single module and propagates allocas usage through +functions calls. + +When used with ThinLTO, the global stage performs a whole program analysis over +the Module Summary Index. + +Testing +======= + +The analysis is covered with lit tests. + +We expect that users can tolerate false classification of variables 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 to 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 information in the +``ASanStackVariableDescription``. Then if AddressSanitizer detects a bug on +a 'safe' variable we can produce an additional report to let the user know that +probably Stack Safety Analysis failed and we should check for a bug in the +compiler. + diff --git a/llvm/docs/index.rst b/llvm/docs/index.rst index df70de095bd9..b60daccc1f31 100644 --- a/llvm/docs/index.rst +++ b/llvm/docs/index.rst @@ -302,6 +302,7 @@ For API clients and LLVM developers. PDB/index CFIVerify SpeculativeLoadHardening + StackSafetyAnalysis :doc:`WritingAnLLVMPass` Information on how to write LLVM transformations and analyses. @@ -438,6 +439,10 @@ For API clients and LLVM developers. :doc:`SpeculativeLoadHardening` A description of the Speculative Load Hardening mitigation for Spectre v1. +:doc:`StackSafetyAnalysis` + This document describes the design of the stack safety analysis of local + variables. + Development Process Documentation =================================