SIL: add the borrowed-from instruction.

It declares from which enclosing values a guaranteed phi argument is borrowed from.

Author: eeckstein

SwiftCompilerSources/Sources/SIL/Argument.swift

@@ -139,6 +139,15 @@ public struct Phi {
     value.ownership == .owned || value.isReborrow
   }
 
+  public var borrowedFrom: BorrowedFromInst? {
+    for use in value.uses {
+      if let bfi = use.forwardingBorrowedFromUser {
+        return bfi
+      }
+    }
+    return nil
+  }
+
   public static func ==(lhs: Phi, rhs: Phi) -> Bool {
     lhs.value === rhs.value
   }
@@ -148,6 +157,15 @@ public struct Phi {
   }
 }
 
+extension Operand {
+  public var forwardingBorrowedFromUser: BorrowedFromInst? {
+    if let bfi = instruction as? BorrowedFromInst, index == 0 {
+      return bfi
+    }
+    return nil
+  }
+}
+
 public struct TerminatorResult {
   public let value: Argument
 

SwiftCompilerSources/Sources/SIL/Builder.swift

@@ -184,6 +184,13 @@ public struct Builder {
     return notifyNew(bridged.createBeginBorrow(value.bridged).getAs(BeginBorrowInst.self))
   }
 
+  public func createBorrowedFrom(borrowedValue: Value, enclosingValues: [Value]) -> BorrowedFromInst {
+    let bfi = enclosingValues.withBridgedValues { valuesRef in
+      return bridged.createBorrowedFrom(borrowedValue.bridged, valuesRef)
+    }
+    return notifyNew(bfi.getAs(BorrowedFromInst.self))
+  }
+
   @discardableResult
   public func createEndBorrow(of beginBorrow: Value) -> EndBorrowInst {
     return notifyNew(bridged.createEndBorrow(beginBorrow.bridged).getAs(EndBorrowInst.self))

SwiftCompilerSources/Sources/SIL/ForwardingInstruction.swift

@@ -441,6 +441,14 @@ extension LinearFunctionExtractInst: ForwardingInstruction {
   public var canForwardOwnedValues: Bool { true }
 }
 
+extension BorrowedFromInst: ForwardingInstruction {
+  public var singleForwardedOperand: Operand? { operands[0] }
+  public var preservesIdentity: Bool { true }
+  public var preservesRepresentation: Bool { true }
+  public var canForwardGuaranteedValues: Bool { true }
+  public var canForwardOwnedValues: Bool { false }
+}
+
 // -----------------------------------------------------------------------------
 // ownership transition instructions
 

SwiftCompilerSources/Sources/SIL/Instruction.swift

@@ -956,6 +956,18 @@ final public class BridgeObjectToRefInst : SingleValueInstruction, UnaryInstruct
 
 final public class BridgeObjectToWordInst : SingleValueInstruction, UnaryInstruction {}
 
+final public class BorrowedFromInst : SingleValueInstruction, BorrowIntroducingInstruction {
+  public var borrowedValue: Value { operands[0].value }
+  public var borrowedPhi: Phi { Phi(borrowedValue)! }
+  public var enclosingOperands: OperandArray {
+    let ops = operands
+    return ops[1..<ops.count]
+  }
+  public var enclosingValues: LazyMapSequence<LazySequence<OperandArray>.Elements, Value> {
+    enclosingOperands.values
+  }
+}
+
 final public class ProjectBoxInst : SingleValueInstruction, UnaryInstruction {
   public var box: Value { operand.value }
   public var fieldIndex: Int { bridged.ProjectBoxInst_fieldIndex() }

SwiftCompilerSources/Sources/SIL/Registration.swift

@@ -201,6 +201,7 @@ public func registerSILClasses() {
   register(ExtractExecutorInst.self)
   register(BeginAccessInst.self)
   register(BeginBorrowInst.self)
+  register(BorrowedFromInst.self)
   register(ProjectBoxInst.self)
   register(ProjectExistentialBoxInst.self)
   register(CopyValueInst.self)

docs/SIL.rst

@@ -4615,6 +4615,38 @@ We require that ``%1`` and ``%0`` have the same type ignoring SILValueCategory.
 
 This instruction is only valid in functions in Ownership SSA form.
 
+borrowed from
+`````````````
+
+::
+
+   sil-instruction ::= 'borrowed' sil-operand 'from' '(' (sil-operand (',' sil-operand)*)? ')'
+
+   bb1(%1 : @owned $T, %2 : @guaranteed $T):
+     %3 = borrowed %2 : $T from (%1 : $T, %0 : $S)
+     // %3 has type $T and guaranteed ownership
+
+Declares from which enclosing values a guaranteed phi argument is borrowed
+from.
+An enclosing value is either a dominating borrow introducer (``%0``) of the
+borrowed operand (``%2``) or an adjacent phi-argument in the same block
+(``%1``).
+In case of an adjacent phi, all incoming values of the adjacent phi must be
+borrow introducers for the corresponding incoming value of the borrowed
+operand in all predecessor blocks.
+
+The borrowed operand (``%2``) must be a guaranteed phi argument and is
+forwarded to the instruction result.
+
+The list of enclosing values (operands after ``from``) can be empty if the
+borrowed operand stems from a borrow introducer with no enclosing value, e.g.
+a ``load_borrow``.
+
+Guaranteed phi arguments must not have other users than borrowed-from
+instructions.
+
+This instruction is only valid in functions in Ownership SSA form.
+
 end_lifetime
 ````````````
 

include/swift/SIL/InstWrappers.h

@@ -279,6 +279,8 @@ class ForwardingOperation {
         &forwardingInst->getOperandRef(RefToBridgeObjectInst::ConvertedOperand);
     case SILInstructionKind::TuplePackExtractInst:
       return &forwardingInst->getOperandRef(TuplePackExtractInst::TupleOperand);
+    case SILInstructionKind::BorrowedFromInst:
+      return &forwardingInst->getOperandRef(0);
     default:
       int numRealOperands = forwardingInst->getNumRealOperands();
       if (numRealOperands == 0) {

include/swift/SIL/OwnershipUtils.h

@@ -254,6 +254,7 @@ class BorrowingOperandKind {
   enum Kind : uint8_t {
     Invalid = 0,
     BeginBorrow,
+    BorrowedFrom,
     StoreBorrow,
     BeginApply,
     Branch,
@@ -279,6 +280,8 @@ class BorrowingOperandKind {
       return Kind::Invalid;
     case SILInstructionKind::BeginBorrowInst:
       return Kind::BeginBorrow;
+    case SILInstructionKind::BorrowedFromInst:
+      return Kind::BorrowedFrom;
     case SILInstructionKind::StoreBorrowInst:
       return Kind::StoreBorrow;
     case SILInstructionKind::BeginApplyInst:
@@ -399,6 +402,7 @@ struct BorrowingOperand {
     case BorrowingOperandKind::Invalid:
       llvm_unreachable("Using invalid case?!");
     case BorrowingOperandKind::BeginBorrow:
+    case BorrowingOperandKind::BorrowedFrom:
     case BorrowingOperandKind::StoreBorrow:
     case BorrowingOperandKind::BeginApply:
     case BorrowingOperandKind::Apply:
@@ -431,6 +435,7 @@ struct BorrowingOperand {
     case BorrowingOperandKind::Invalid:
       llvm_unreachable("Using invalid case?!");
     case BorrowingOperandKind::BeginBorrow:
+    case BorrowingOperandKind::BorrowedFrom:
     case BorrowingOperandKind::Branch:
       return true;
     case BorrowingOperandKind::StoreBorrow:

include/swift/SIL/SILBridging.h

@@ -1163,6 +1163,8 @@ struct BridgedBuilder{
   SWIFT_IMPORT_UNSAFE BRIDGED_INLINE BridgedInstruction createFunctionRef(BridgedFunction function) const;
   SWIFT_IMPORT_UNSAFE BRIDGED_INLINE BridgedInstruction createCopyValue(BridgedValue op) const;
   SWIFT_IMPORT_UNSAFE BRIDGED_INLINE BridgedInstruction createBeginBorrow(BridgedValue op) const;
+  SWIFT_IMPORT_UNSAFE BRIDGED_INLINE BridgedInstruction createBorrowedFrom(BridgedValue borrowedValue,
+                                                                           BridgedValueArray enclosingValues) const;
   SWIFT_IMPORT_UNSAFE BRIDGED_INLINE BridgedInstruction createEndBorrow(BridgedValue op) const;
   SWIFT_IMPORT_UNSAFE BRIDGED_INLINE BridgedInstruction createCopyAddr(BridgedValue from, BridgedValue to,
                                           bool takeSource, bool initializeDest) const;

include/swift/SIL/SILBridgingImpl.h

@@ -1575,6 +1575,13 @@ BridgedInstruction BridgedBuilder::createBeginBorrow(BridgedValue op) const {
   return {unbridged().createBeginBorrow(regularLoc(), op.getSILValue())};
 }
 
+BridgedInstruction BridgedBuilder::createBorrowedFrom(BridgedValue borrowedValue,
+                                                      BridgedValueArray enclosingValues) const {
+  llvm::SmallVector<swift::SILValue, 16> evs;
+  return {unbridged().createBorrowedFrom(regularLoc(), borrowedValue.getSILValue(),
+                                         enclosingValues.getValues(evs))};
+}
+
 BridgedInstruction BridgedBuilder::createEndBorrow(BridgedValue op) const {
   return {unbridged().createEndBorrow(regularLoc(), op.getSILValue())};
 }