[DebugInfo] Adding DIExpression into SIL

docs/SIL.rst

@@ -3489,7 +3489,7 @@ debug_value
 
 ::
 
-  sil-instruction ::= debug_value '[poison]'? sil-operand (',' debug-var-attr)*
+  sil-instruction ::= debug_value '[poison]'? sil-operand (',' debug-var-attr)* advanced-debug-var-attr* (',' 'expr' debug-info-expr)?
 
   debug_value %1 : $Int
 
@@ -3506,10 +3506,26 @@ The operand must have loadable type.
    debug-var-attr ::= 'name' string-literal
    debug-var-attr ::= 'argno' integer-literal
 
+::
+
+  advanced-debug-var-attr ::= '(' 'name' string-literal (',' sil-instruction-source-info)? ')'
+  advanced-debug-var-attr ::= 'type' sil-type
+
+::
+
+  debug-info-expr   ::= di-expr-operand (':' di-expr-operand)*
+  di-expr-operand   ::= di-expr-operator (':' sil-operand)*
+  di-expr-operator  ::= 'op_fragment'
+
 There are a number of attributes that provide details about the source
 variable that is being described, including the name of the
 variable. For function and closure arguments ``argno`` is the number
-of the function argument starting with 1.
+of the function argument starting with 1. The advanced debug variable
+attributes represent source locations and type of the source variable
+when it was originally declared. It is useful when we're indirectly
+associating the SSA value with the source variable (via di-expression,
+for example) in which case SSA value's type is different from that of
+source variable.
 
 If the '[poison]' flag is set, then all references within this debug
 value will be overwritten with a sentinel at this point in the
@@ -3520,12 +3536,32 @@ generated until OSSA islowered. They are not expected to be serialized
 within the module, and the pipeline is not expected to do any
 significant code motion after lowering.
 
+Debug info expression (di-expression) is a powerful method to connect SSA
+value with the source variable in an indirect fashion. For example,
+we can use the ``op_fragment`` operator to specify that the SSA value
+is originated from a struct field inside the source variable (which has
+an aggregate data type). Di-expression in SIL works similarly to LLVM's
+``!DIExpression`` metadata. Where both of them adopt a stack based
+execution model to evaluate the expression. The biggest difference between
+them is that LLVM always represent ``!DIExpression`` elements as 64-bit
+integers, while SIL's di-expression can have elements with various types,
+like AST nodes or strings. Here is an example::
+
+  struct MyStruct {
+    var x: Int
+    var y: Int
+  }
+  ...
+  debug_value %1 : $Int, var, (name "the_struct", loc "file.swift":8:7), type $MyStruct, expr op_fragment:#MyStruct.y, loc "file.swift":9:4
+
+In the snippet above, source variable "the_struct" has an aggregate type ``$MyStruct`` and we use di-expression with ``op_fragment`` operator to associate ``%1`` to the ``y`` member variable inside "the_struct". Note that the extra source location directive follows rigt after ``name "the_struct"`` indicate that "the_struct" was originally declared in line 8, but not until line 9, the current ``debug_value`` instruction's source location, does member ``y`` got updated with SSA value ``%1``.
+
 debug_value_addr
 ````````````````
 
 ::
 
-  sil-instruction ::= debug_value_addr sil-operand (',' debug-var-attr)*
+  sil-instruction ::= debug_value_addr sil-operand (',' debug-var-attr)* advanced-debug-var-attr* (',' 'expr' debug-info-expr)?
 
   debug_value_addr %7 : $*SomeProtocol
 
@@ -3534,6 +3570,7 @@ has changed value to the specified operand.  The declaration in
 question is identified by the SILLocation attached to the
 debug_value_addr instruction.
 
+Note that this instruction can be replaced by ``debug_value`` + di-expression operator that is equivalent to LLVM's ``DW_OP_deref``.
 
 Accessing Memory
 ~~~~~~~~~~~~~~~~

include/swift/AST/DiagnosticsParse.def

@@ -589,15 +589,20 @@ ERROR(sil_missing_substitutions,none,
       "missing substitutions", ())
 ERROR(sil_too_many_substitutions,none,
       "too many substitutions", ())
-ERROR(sil_dbg_unknown_key,none,
-      "unknown key '%0' in debug variable declaration", (StringRef))
 ERROR(sil_objc_with_tail_elements,none,
       "alloc_ref [objc] cannot have tail allocated elements", ())
 ERROR(sil_expected_access_kind,none,
       "%0 instruction must have explicit access kind", (StringRef))
 ERROR(sil_expected_access_enforcement,none,
       "%0 instruction must have explicit access enforcement", (StringRef))
 
+ERROR(sil_dbg_unknown_key,none,
+      "unknown key '%0' in debug variable declaration", (StringRef))
+ERROR(sil_dbg_unknown_expr_part,none,
+      "unrecognized debug info expression %0", (StringRef))
+ERROR(sil_dbg_expr_expect_operand_kind,none,
+      "operator %0 expects a %1 kind operand here", (StringRef, StringRef))
+
 ERROR(sil_keypath_expected_component_kind,none,
       "expected keypath component kind", ())
 ERROR(sil_keypath_unknown_component_kind,none,

include/swift/SIL/SILDebugInfoExpression.h

@@ -0,0 +1,213 @@
+//===--- SILDebugInfoExpression.h - DIExpression for SIL --------*- C++ -*-===//
+//
+// This source file is part of the Swift.org open source project
+//
+// Copyright (c) 2014 - 2017 Apple Inc. and the Swift project authors
+// Licensed under Apache License v2.0 with Runtime Library Exception
+//
+// See https://swift.org/LICENSE.txt for license information
+// See https://swift.org/CONTRIBUTORS.txt for the list of Swift project authors
+//
+//===----------------------------------------------------------------------===//
+///
+/// \file
+/// This file contains types that model debug info expressions in SIL. Including
+/// (debug info) operator and operand.
+///
+//===----------------------------------------------------------------------===//
+#ifndef SWIFT_SIL_DEBUGINFOEXPRESSION_H
+#define SWIFT_SIL_DEBUGINFOEXPRESSION_H
+#include "swift/AST/Decl.h"
+#include "llvm/ADT/ArrayRef.h"
+#include "llvm/ADT/Optional.h"
+#include "llvm/ADT/iterator_range.h"
+#include "llvm/Support/raw_ostream.h"
+
+namespace swift {
+class TailAllocatedDebugVariable;
+
+/// Operator in a debug info expression
+enum class SILDIExprOperator : unsigned {
+  INVALID = 0,
+  /// Dereferences the SSA value
+  Dereference,
+  /// Specifies that the SSA value is a fragment (sub-field) of the
+  /// associated source variable. This operator takes a single
+  /// VarDecl operand pointing to the field declaration.
+  /// Note that this directive can only appear at the end of an
+  /// expression.
+  Fragment
+};
+
+/// Represents a single component in a debug info expression.
+/// Including operator and operand.
+struct SILDIExprElement {
+  enum Kind {
+    /// A di-expression operator
+    OperatorKind,
+    /// An operand that has declaration type
+    DeclKind
+  };
+
+private:
+  Kind OpKind;
+
+  union {
+    SILDIExprOperator Operator;
+    Decl *Declaration;
+  };
+
+  explicit SILDIExprElement(Kind OpK) : OpKind(OpK) {}
+
+public:
+  Kind getKind() const { return OpKind; }
+
+  SILDIExprOperator getAsOperator() const {
+    return OpKind == OperatorKind ? Operator : SILDIExprOperator::INVALID;
+  }
+
+  Decl *getAsDecl() const { return OpKind == DeclKind ? Declaration : nullptr; }
+
+  static SILDIExprElement createOperator(SILDIExprOperator Op) {
+    SILDIExprElement DIOp(OperatorKind);
+    DIOp.Operator = Op;
+    return DIOp;
+  }
+
+  static SILDIExprElement createDecl(Decl *D) {
+    SILDIExprElement DIOp(DeclKind);
+    DIOp.Declaration = D;
+    return DIOp;
+  }
+};
+
+/// For a given SILDIExprOperator, provides information
+/// like its textual name and operand types.
+struct SILDIExprInfo {
+  StringRef OpText;
+  SmallVector<SILDIExprElement::Kind, 2> OperandKinds;
+
+  static const SILDIExprInfo *get(SILDIExprOperator Op);
+};
+
+/// A DIExpr operand is consisting of a SILDIExprOperator and
+/// SILDIExprElement arguments following after.
+struct SILDIExprOperand : public llvm::ArrayRef<SILDIExprElement> {
+  // Reuse all the ctors
+  using llvm::ArrayRef<SILDIExprElement>::ArrayRef;
+
+  SILDIExprOperator getOperator() const {
+    assert(size() && "empty DIExpr operand");
+    const SILDIExprElement &First = front();
+    return First.getAsOperator();
+  }
+
+  size_t getNumArg() const {
+    assert(size() && "empty DIExpr operand");
+    return size() - 1;
+  }
+
+  llvm::ArrayRef<SILDIExprElement> args() const {
+    return drop_front();
+  }
+};
+
+/// Represents a debug info expression in SIL
+class SILDebugInfoExpression {
+  friend class TailAllocatedDebugVariable;
+  llvm::SmallVector<SILDIExprElement, 2> Elements;
+
+public:
+  SILDebugInfoExpression() = default;
+
+  explicit SILDebugInfoExpression(llvm::ArrayRef<SILDIExprElement> EL)
+      : Elements(EL.begin(), EL.end()) {}
+
+  size_t getNumElements() const { return Elements.size(); }
+
+  using iterator = typename decltype(Elements)::iterator;
+  using const_iterator = typename decltype(Elements)::const_iterator;
+
+  iterator element_begin() { return Elements.begin(); }
+  iterator element_end() { return Elements.end(); }
+
+  const_iterator element_begin() const { return Elements.begin(); }
+  const_iterator element_end() const { return Elements.end(); }
+
+  llvm::iterator_range<iterator> elements() {
+    return llvm::make_range(element_begin(), element_end());
+  }
+
+  llvm::iterator_range<const_iterator> elements() const {
+    return llvm::make_range(element_begin(), element_end());
+  }
+
+  const SILDIExprElement &getElement(size_t index) const {
+    assert(index < Elements.size());
+    return Elements[index];
+  }
+
+  void push_back(const SILDIExprElement &Element) {
+    Elements.push_back(Element);
+  }
+
+  /// The iterator for SILDIExprOperand
+  class op_iterator {
+    friend class SILDebugInfoExpression;
+
+    SILDIExprOperand Current;
+    llvm::ArrayRef<SILDIExprElement> Remain;
+
+    void increment();
+
+    explicit
+    op_iterator(llvm::ArrayRef<SILDIExprElement> Remain): Remain(Remain) {
+      increment();
+    }
+
+  public:
+    op_iterator() = default;
+    op_iterator(const op_iterator &) = default;
+
+    const SILDIExprOperand &operator*() const { return Current; }
+    const SILDIExprOperand *operator->() const { return &Current; }
+
+    // Pre increment
+    op_iterator &operator++() {
+      increment();
+      return *this;
+    }
+
+    // Post increment
+    op_iterator operator++(int) {
+      op_iterator This(*this);
+      increment();
+      return This;
+    }
+
+    bool operator==(const op_iterator &Other) const {
+      return (Current.empty() && Other.Current.empty()) ||
+             (Current.data() == Other.Current.data() &&
+              Current.size() == Other.Current.size());
+    }
+    bool operator!=(const op_iterator &Other) const {
+      return !(Other == *this);
+    }
+  };
+
+  op_iterator operand_begin() const {
+    return op_iterator(Elements);
+  }
+  op_iterator operand_end() const {
+    return op_iterator(llvm::ArrayRef<SILDIExprElement>{});
+  }
+
+  llvm::iterator_range<op_iterator> operands() const {
+    return llvm::make_range(operand_begin(), operand_end());
+  }
+
+  /// Return true if this expression is not empty
+  inline operator bool() const { return Elements.size(); }
+};
+} // end namespace swift
+#endif