[SIL] Added new test_specification instruction.

The new instruction exists only to be used in tests.  The idea is to
specify tests that ought to be run "in the context" of the containing
function.

Author: nate-chandler

docs/SIL.rst

@@ -3924,6 +3924,52 @@ SIL DIExpression can have elements with various types, like AST nodes or strings
 
 The ``[trace]`` flag is available for compiler unit testing. It is not produced during normal compilation. It is used combination with internal logging and optimization controls to select specific values to trace or to transform. For example, liveness analysis combines all "traced" values into a single live range with multiple definitions. This exposes corner cases that cannot be represented by passing valid SIL through the pipeline.
 
+Testing
+~~~~~~~
+
+test_specification
+``````````````````
+::
+
+  sil-instruction ::= 'test_specification' string-literal
+
+  test_specification "parsing @trace[3] @function[other].block[2].instruction[1]"
+
+Exists only for writing FileCheck tests.  Specifies a list of test arguments
+which should be used in order to run a particular test "in the context" of the
+function containing the instruction.
+
+Parsing of these test arguments is done via ``parseTestArgumentsFromSpecification``.
+
+The following types of test arguments are supported:
+
+- boolean: true false
+- unsigned integer: 0...ULONG_MAX
+- string
+- function: @function <-- the current function
+            @function[uint] <-- function at index ``uint``
+            @function[name] <-- function named ``name``
+- block: @block <-- the first block
+         @block[uint] <-- the block at index ``uint``
+         @{function}.{block} <-- the indicated block in the indicated function
+         Example: @function[foo].block[2]
+- trace: @trace <-- the first ``debug_value [trace]`` in the current function
+         @trace[uint] <-- the ``debug_value [trace]`` at index ``uint``
+         @{function}.{trace} <-- the indicated trace in the indicated function
+         Example: @function[bar].trace
+- instruction: @instruction <-- the first instruction
+               @instruction[uint] <-- the instruction at index ``uint``
+               @{function}.{instruction} <-- the indicated instruction in the indicated function
+               Example: @function[baz].instruction[19]
+               @{block}.{instruction} <-- the indicated instruction in the indicated block
+               Example: @function[bam].block.instruction
+- operand: @operand <-- the first operand
+           @operand[uint] <-- the operand at index ``uint``
+           @{instruction}.{operand} <-- the indicated operand of the indicated instruction
+           Example: @block[19].instruction[2].operand[3]
+           Example: @function[2].instruction.operand
+
+
 Profiling
 ~~~~~~~~~
 

include/swift/AST/DiagnosticsParse.def

@@ -539,6 +539,8 @@ ERROR(expected_sil_profiler_counter_total,none,
       "expected profiler counter total", ())
 ERROR(expected_sil_profiler_counter_hash,none,
       "expected profiler counter hash", ())
+ERROR(expected_sil_test_specification_body,none,
+      "expected a string consisting of the space-separated test arguments", ())
 
 // SIL Values
 ERROR(sil_value_redefinition,none,

include/swift/SIL/SILBuilder.h

@@ -988,6 +988,13 @@ class SILBuilder {
     return createDebugValue(Loc, src, Var);
   }
 
+  TestSpecificationInst *
+  createTestSpecificationInst(SILLocation Loc,
+                              StringRef ArgumentsSpecification) {
+    return insert(TestSpecificationInst::create(
+        getSILDebugLocation(Loc), ArgumentsSpecification, getModule()));
+  }
+
 #define NEVER_LOADABLE_CHECKED_REF_STORAGE(Name, ...) \
   Load##Name##Inst *createLoad##Name(SILLocation Loc, \
                                      SILValue src, \

include/swift/SIL/SILCloner.h

@@ -2631,6 +2631,15 @@ void SILCloner<ImplClass>::visitIncrementProfilerCounterInst(
                               Inst->getNumCounters(), Inst->getPGOFuncHash()));
 }
 
+template <typename ImplClass>
+void SILCloner<ImplClass>::visitTestSpecificationInst(
+    TestSpecificationInst *Inst) {
+  getBuilder().setCurrentDebugScope(getOpScope(Inst->getDebugScope()));
+  recordClonedInstruction(Inst, getBuilder().createTestSpecificationInst(
+                                    getOpLocation(Inst->getLoc()),
+                                    Inst->getArgumentsSpecification()));
+}
+
 template<typename ImplClass>
 void
 SILCloner<ImplClass>::visitIndexAddrInst(IndexAddrInst *Inst) {

include/swift/SIL/SILInstruction.h

@@ -4933,6 +4933,32 @@ class DebugValueInst final
   }
 };
 
+class TestSpecificationInst final
+    : public InstructionBase<SILInstructionKind::TestSpecificationInst,
+                             NonValueInstruction>,
+      private llvm::TrailingObjects<TestSpecificationInst, char> {
+  friend TrailingObjects;
+  friend SILBuilder;
+
+  unsigned ArgumentsSpecificationLength;
+
+  TestSpecificationInst(SILDebugLocation Loc,
+                        unsigned ArgumentsSpecificationLength)
+      : InstructionBase(Loc),
+        ArgumentsSpecificationLength(ArgumentsSpecificationLength) {}
+
+  static TestSpecificationInst *
+  create(SILDebugLocation Loc, StringRef argumentsSpecification, SILModule &M);
+
+public:
+  StringRef getArgumentsSpecification() const {
+    return StringRef(getTrailingObjects<char>(), ArgumentsSpecificationLength);
+  }
+
+  ArrayRef<Operand> getAllOperands() const { return {}; }
+  MutableArrayRef<Operand> getAllOperands() { return {}; }
+};
+
 /// An abstract class representing a load from some kind of reference storage.
 template <SILInstructionKind K>
 class LoadReferenceInstBase

include/swift/SIL/SILNodes.def

@@ -765,6 +765,8 @@ NON_VALUE_INST(MarkFunctionEscapeInst, mark_function_escape,
                SILInstruction, None, DoesNotRelease)
 NON_VALUE_INST(DebugValueInst, debug_value,
                SILInstruction, None, DoesNotRelease)
+NON_VALUE_INST(TestSpecificationInst, test_specification,
+               SILInstruction, None, DoesNotRelease)
 #define NEVER_OR_SOMETIMES_LOADABLE_CHECKED_REF_STORAGE(Name, name, ...) \
   NON_VALUE_INST(Store##Name##Inst, store_##name, \
                  SILInstruction, MayWrite, DoesNotRelease)

lib/IRGen/IRGenSIL.cpp

@@ -1384,6 +1384,9 @@ class IRGenSILFunction :
   void visitLinearFunctionExtractInst(LinearFunctionExtractInst *i);
   void visitDifferentiabilityWitnessFunctionInst(
       DifferentiabilityWitnessFunctionInst *i);
+  void visitTestSpecificationInst(TestSpecificationInst *i) {
+    llvm_unreachable("test-only instruction in Lowered SIL?!");
+  }
 
 #define LOADABLE_REF_STORAGE_HELPER(Name)                                      \
   void visitRefTo##Name##Inst(RefTo##Name##Inst *i);                           \

lib/SIL/IR/OperandOwnership.cpp

@@ -120,6 +120,7 @@ SHOULD_NEVER_VISIT_INST(ReleaseValueAddr)
 SHOULD_NEVER_VISIT_INST(StrongRelease)
 SHOULD_NEVER_VISIT_INST(GetAsyncContinuation)
 SHOULD_NEVER_VISIT_INST(IncrementProfilerCounter)
+SHOULD_NEVER_VISIT_INST(TestSpecification)
 
 #define ALWAYS_OR_SOMETIMES_LOADABLE_CHECKED_REF_STORAGE(Name, ...)            \
   SHOULD_NEVER_VISIT_INST(StrongRetain##Name)                                  \

lib/SIL/IR/SILInstructions.cpp

@@ -456,6 +456,21 @@ IncrementProfilerCounterInst *IncrementProfilerCounterInst::create(
   return Inst;
 }
 
+TestSpecificationInst *
+TestSpecificationInst::create(SILDebugLocation Loc,
+                              StringRef ArgumentsSpecification, SILModule &M) {
+  auto ArgumentsSpecificationLength = ArgumentsSpecification.size();
+  auto Size = totalSizeToAlloc<char>(ArgumentsSpecificationLength);
+  auto Buffer = M.allocateInst(Size, alignof(TestSpecificationInst));
+
+  auto *Inst =
+      ::new (Buffer) TestSpecificationInst(Loc, ArgumentsSpecificationLength);
+  std::uninitialized_copy(ArgumentsSpecification.begin(),
+                          ArgumentsSpecification.end(),
+                          Inst->getTrailingObjects<char>());
+  return Inst;
+}
+
 InitBlockStorageHeaderInst *
 InitBlockStorageHeaderInst::create(SILFunction &F,
                                SILDebugLocation DebugLoc, SILValue BlockStorage,

lib/SIL/IR/SILPrinter.cpp

@@ -2410,7 +2410,11 @@ class SILPrinter : public SILInstructionVisitor<SILPrinter> {
   void visitReturnInst(ReturnInst *RI) {
     *this << getIDAndType(RI->getOperand());
   }
-  
+
+  void visitTestSpecificationInst(TestSpecificationInst *TSI) {
+    *this << QuotedString(TSI->getArgumentsSpecification());
+  }
+
   void visitThrowInst(ThrowInst *TI) {
     *this << getIDAndType(TI->getOperand());
   }