[TableGen] Add `!dump` and `dump`.

[fpetrogalli]

Summary

This allows dumping expressions `(Init *)` as soon as they become
concrete. Both of these take a string as the first operand that
prefixes the dump of the expression.

`!dump` can be used in a expression/functional context. For example:

    !foreach(i, lst, !dump(i))

`dump` can be used in a "statement" context:

    def c: C<3>;
    dump c;

`dump` is implemented as a syntactic sugar. The above `dump` is parsed into:

    assert 1, !cast<string>(!dump(c));

Original patch from Adam Nemet <[e-mail]>

[fpetrogalli]

Following the decision to abandon D156420, I have updated this patch with the correct docs, comments and tests.

[fpetrogalli]

Update some of the test cases to show how dump can be used to produce the labels that can be useful for tracking the dump of a variable in debugging
sessions.

[tra]

I think we're commingling two different things here.

• representing a value as a string
• printing something out for debugging purposes.

While for debugging we may usually want to do both, it would be very useful to be able to use them independently. That would allow doing things like dump("got a pair of values [" # !repr(value_A) # " : " # !repr(value_B # "]")).

We could add some glue to dump/!dump() so that they wrap non-string arguments into !repr() automatically.

llvm/docs/TableGen/ProgRef.rst

1252–1253

I'm still not fun of dump or !dump printing anything other than what the user passed to it. The The value of X is part should not be hardcoded and should be up to the user what they may want to print in addition to the value itself. If they need something extra, they are free to add more dump statements.

1695

This may need updating as dump only accepts a single value argument w/o prefix.

llvm/lib/TableGen/TGParser.cpp

1345

No more String.

[nhaehnle]

In D157492#4577657, @tra wrote:

I think we're commingling two different things here.

• representing a value as a string
• printing something out for debugging purposes.

While for debugging we may usually want to do both, it would be very useful to be able to use them independently. That would allow doing things like dump("got a pair of values [" # !repr(value_A) # " : " # !repr(value_B # "]")).

We could add some glue to dump/!dump() so that they wrap non-string arguments into !repr() automatically.

I like this idea.

llvm/docs/TableGen/ProgRef.rst

1252–1253

Is this part of the documentation still correct? It doesn't appear to match the test cases.

llvm/lib/TableGen/Record.cpp

805

Use '\n' for single-character output.

llvm/lib/TableGen/TGParser.cpp

3857

Typo: Expected

Also: why "second" operand?

llvm/docs/TableGen/ProgRef.rst

 begin with an integer. In case of ambiguity, a token is interpreted as a
 numeric literal rather than an identifier.
 
 TableGen has the following reserved keywords, which cannot be used as
 identifiers::
 
    assert     bit           bits          class         code
    dag        def           else          false         foreach
-   defm       defset        defvar        field         if
-   in         include       int           let           list
-   multiclass string        then          true
+   defm       defset        defvar        dump          field
+   if         in            include       int           let
+   list       multiclass    string        then          true
 
 .. warning::
   The ``field`` reserved word is deprecated, except when used with the
   CodeEmitterGen backend where it's used to distinguish normal record
   fields from encoding fields.
 
 Bang operators
 --------------

 each loop iteration, so their value in one iteration is not available in
 the next iteration.  The following ``defvar`` will not work::
 
   defvar i = !add(i, 1);
 
 Variables can also be defined with ``defvar`` in a record body. See
 `Defvar in a Record Body`_ for more details.
 
+``dump`` --- print the content of a variable or record
+------------------------------------------------------
+
+A ``dump`` statement prints the content of a variable or a record to
+standard error output.
+
+.. productionlist::
+   Dump: "dump"  `TokIdentifier` ";"
+
+Example: the following statements will print ``The value of X is 0``
+to standard output.
+
+  defvar X = 0;
+  dump X;
+
 ``foreach`` --- iterate over a sequence of statements
 -----------------------------------------------------
 
 The ``foreach`` statement iterates over a series of statements, varying a
 variable over a sequence of values.
 
 .. productionlist::
    Foreach: "foreach" `ForeachIterator` "in" "{" `Statement`* "}"
``!dag(``\ *op*\ ``,`` *arguments*\ ``,`` *names*\ ``)``
 
     Example: ``!dag(op, [a1, a2, ?], ["name1", "name2", "name3"])`` results in
     ``(op a1-value:$name1, a2-value:$name2, ?:$name3)``.
 
 ``!div(``\ *a*\ ``,`` *b*\ ``)``
     This operator performs signed division of *a* by *b*, and produces the quotient.
     Division by 0 produces an error. Division of INT64_MIN by -1 produces an error.
 
+``!dump(``\ *name*\ ``)``
+    This operator will print the value of *name*.
+
+     The following example will instantiate the class ``X`` with a
+     value of ``n`` equal to ``0``, and print the value of X as the
+     string ``0`` to standard output: ``class X<int n> {...} def :
+     X<!dump("n = ", 0)>;``
+
 ``!empty(``\ *a*\ ``)``
     This operator produces 1 if the string, list, or DAG *a* is empty; 0 otherwise.
     A dag is empty if it has no arguments; the operator does not count.
 
 ``!eq(`` *a*\ `,` *b*\ ``)``
     This operator produces 1 if *a* is equal to *b*; 0 otherwise.
     The arguments must be ``bit``, ``bits``, ``int``, ``string``, or
     record values. Use ``!cast<string>`` to compare other types of objects.

llvm/include/llvm/TableGen/Record.h

enum UnaryOp : uint8_t {
     TOUPPER,
     CAST,
     NOT,
     HEAD,
     TAIL,
     SIZE,
     EMPTY,
     GETDAGOP,
-    LOG2
+    LOG2,
+    DUMP
   };
 
 private:
   Init *LHS;
 
   UnOpInit(UnaryOp opc, Init *lhs, RecTy *Type)
     : OpInit(IK_UnOpInit, Type, opc), LHS(lhs) {}
 

llvm/lib/TableGen/Record.cpp

 
 void UnOpInit::Profile(FoldingSetNodeID &ID) const {
   ProfileUnOpInit(ID, getOpcode(), getOperand(), getType());
 }
 
 Init *UnOpInit::Fold(Record *CurRec, bool IsFinal) const {
   RecordKeeper &RK = getRecordKeeper();
   switch (getOpcode()) {
+  case DUMP: {
+    if (LHS->isConcrete()) {
+      if (const auto *Def = dyn_cast<DefInit>(LHS))
+        errs() << *Def->getDef() << "\n";
+      else
+        errs() << LHS->getAsString() << "\n";
+      return LHS;
+    }
+    break;
+  }
+
   case TOLOWER:
     if (StringInit *LHSs = dyn_cast<StringInit>(LHS))
       return StringInit::get(RK, LHSs->getValue().lower());
     break;
   case TOUPPER:
     if (StringInit *LHSs = dyn_cast<StringInit>(LHS))
       return StringInit::get(RK, LHSs->getValue().upper());
     break;
std::string UnOpInit::getAsString() const {
   case GETDAGOP: Result = "!getdagop"; break;
   case LOG2 : Result = "!logtwo"; break;
   case TOLOWER:
     Result = "!tolower";
     break;
   case TOUPPER:
     Result = "!toupper";
     break;
+  case DUMP:
+    Result = "!dump";
+    break;
   }
   return Result + "(" + LHS->getAsString() + ")";
 }
 
 static void
 ProfileBinOpInit(FoldingSetNodeID &ID, unsigned Opcode, Init *LHS, Init *RHS,
                  RecTy *Type) {
   ID.AddInteger(Opcode);

llvm/lib/TableGen/TGLexer.h

enum TokKind {
   // Object start tokens.
   OBJECT_START_FIRST,
   Assert = OBJECT_START_FIRST,
   Class,
   Def,
   Defm,
   Defset,
   Defvar,
+  Dump, // Dump is just a syntactic sugar on top of assert and !dump.
   Foreach,
   If,
   Let,
   MultiClass,
   OBJECT_START_LAST = MultiClass,
 
   // Bang operators.
   BANG_OPERATOR_FIRST,
enum TokKind {
   XFilter,
   XFoldl,
   XHead,
   XTail,
   XSize,
   XEmpty,
   XIf,
   XCond,
+  XDump,
   XEq,
   XIsA,
   XDag,
   XNe,
   XLe,
   XLt,
   XGe,
   XGt,

llvm/lib/TableGen/TGLexer.cpp

tgtok::TokKind TGLexer::LexIdentifier() {
   // Match the rest of the identifier regex: [0-9a-zA-Z_]*
   while (isalpha(*CurPtr) || isdigit(*CurPtr) || *CurPtr == '_')
     ++CurPtr;
 
   // Check to see if this identifier is a reserved keyword.
   StringRef Str(IdentStart, CurPtr-IdentStart);
 
   tgtok::TokKind Kind = StringSwitch<tgtok::TokKind>(Str)
                             .Case("int", tgtok::Int)
                             .Case("bit", tgtok::Bit)
                             .Case("bits", tgtok::Bits)
                             .Case("string", tgtok::String)
                             .Case("list", tgtok::List)
                             .Case("code", tgtok::Code)
                             .Case("dag", tgtok::Dag)
                             .Case("class", tgtok::Class)
                             .Case("def", tgtok::Def)
                             .Case("true", tgtok::TrueVal)
                             .Case("false", tgtok::FalseVal)
                             .Case("foreach", tgtok::Foreach)
                             .Case("defm", tgtok::Defm)
                             .Case("defset", tgtok::Defset)
                             .Case("multiclass", tgtok::MultiClass)
                             .Case("field", tgtok::Field)
                             .Case("let", tgtok::Let)
                             .Case("in", tgtok::In)
                             .Case("defvar", tgtok::Defvar)
                             .Case("include", tgtok::Include)
                             .Case("if", tgtok::If)
                             .Case("then", tgtok::Then)
                             .Case("else", tgtok::ElseKW)
                             .Case("assert", tgtok::Assert)
+                            .Case("dump", tgtok::Dump)
                             .Default(tgtok::Id);
 
   // A couple of tokens require special processing.
   switch (Kind) {
     case tgtok::Include:
       if (LexInclude()) return tgtok::Error;
       return Lex();
     case tgtok::Id:
       CurStrVal.assign(Str.begin(), Str.end());
tgtok::TokKind Kind =
           .Cases("getdagop", "getop", tgtok::XGetDagOp) // !getop is deprecated.
           .Case("getdagarg", tgtok::XGetDagArg)
           .Case("getdagname", tgtok::XGetDagName)
           .Case("setdagarg", tgtok::XSetDagArg)
           .Case("setdagname", tgtok::XSetDagName)
           .Case("exists", tgtok::XExists)
           .Case("tolower", tgtok::XToLower)
           .Case("toupper", tgtok::XToUpper)
+          .Case("dump", tgtok::XDump)
           .Default(tgtok::Error);
 
   return Kind != tgtok::Error ? Kind : ReturnError(Start-1, "Unknown operator");
 }
 
 bool TGLexer::prepExitInclude(bool IncludeStackMustBeEmpty) {
   // Report an error, if preprocessor control stack for the current
   // file is not empty.

llvm/lib/TableGen/TGParser.h

private:  // Parser methods.
   bool ParseDefm(MultiClass *CurMultiClass);
   bool ParseDef(MultiClass *CurMultiClass);
   bool ParseDefset();
   bool ParseDefvar(Record *CurRec = nullptr);
   bool ParseForeach(MultiClass *CurMultiClass);
   bool ParseIf(MultiClass *CurMultiClass);
   bool ParseIfBody(MultiClass *CurMultiClass, StringRef Kind);
   bool ParseAssert(MultiClass *CurMultiClass, Record *CurRec = nullptr);
+  bool ParseDump(MultiClass *CurMultiClass, Record *CurRec = nullptr);
   bool ParseTopLevelLet(MultiClass *CurMultiClass);
   void ParseLetList(SmallVectorImpl<LetRecord> &Result);
 
   bool ParseObjectBody(Record *CurRec);
   bool ParseBody(Record *CurRec);
   bool ParseBodyItem(Record *CurRec);
 
   bool ParseTemplateArgList(Record *CurRec);

llvm/lib/TableGen/TGParser.cpp

case tgtok::XIsA: {
 
     if (!consume(tgtok::r_paren)) {
       TokError("expected ')' in !isa");
       return nullptr;
     }
 
     return (IsAOpInit::get(Type, LHS))->Fold();
   }
+  case tgtok::XDump: {
+    // Value ::= !dump '(' String ','  Value ')'
+    Lex.Lex(); // eat the operation
+    if (!consume(tgtok::l_paren)) {
+      TokError("expected '('");
+      return nullptr;
+    }
+    TypedInit *RHS = dyn_cast<TypedInit>(ParseSimpleValue(CurRec));
+    if (!RHS) {
+      Error(Lex.getLoc(), "Expected value as second operand");
+      return nullptr;
+    }
+
+    if (!consume(tgtok::r_paren)) {
+      TokError("expected ')'");
+      return nullptr;
+    }
+
+    return (UnOpInit::get(UnOpInit::DUMP, RHS, RHS->getType()))->Fold(CurRec);
+  }
 
   case tgtok::XExists: {
     // Value ::= !exists '<' Type '>' '(' Value ')'
     Lex.Lex(); // eat the operation
 
     RecTy *Type = ParseOperatorType();
     if (!Type)
       return nullptr;

 ///   BodyItem ::= LET ID OptionalBitList '=' Value ';'
 ///   BodyItem ::= Defvar
 ///   BodyItem ::= Assert
 ///
 bool TGParser::ParseBodyItem(Record *CurRec) {
   if (Lex.getCode() == tgtok::Assert)
     return ParseAssert(nullptr, CurRec);
 
+  if (Lex.getCode() == tgtok::Dump)
+    return ParseDump(nullptr, CurRec);
+
   if (Lex.getCode() == tgtok::Defvar)
     return ParseDefvar(CurRec);
 
   if (Lex.getCode() != tgtok::Let) {
     if (!ParseDeclaration(CurRec, false))
       return true;
 
     if (!consume(tgtok::semi))
bool TGParser::ParseAssert(MultiClass *CurMultiClass, Record *CurRec) {
   if (CurRec)
     CurRec->addAssertion(ConditionLoc, Condition, Message);
   else
     addEntry(std::make_unique<Record::AssertionInfo>(ConditionLoc, Condition,
                                                      Message));
   return false;
 }
 
+bool TGParser::ParseDump(MultiClass *CurMultiClass, Record *CurRec) {
+  Lex.Lex(); // eat the operation
+
+  TypedInit *RHS = dyn_cast<TypedInit>(ParseSimpleValue(CurRec));
+  if (!RHS) {
+    Error(Lex.getLoc(), "Exepcted value as second operand");
+    return true;
+  }
+  if (!consume(tgtok::semi)) {
+    TokError("expected ';'");
+    return true;
+  }
+
+  // Turn this print str, expr into an assert:
+  //   assert 1, !cast<string>(!dump(expr))
+  SMLoc ConditionLoc = Lex.getLoc();
+  Init *Condition = BitInit::get(Records, true);
+  Init *XDump =
+      UnOpInit::get(UnOpInit::DUMP, RHS, RHS->getType())->Fold(CurRec);
+  Init *Message =
+      UnOpInit::get(UnOpInit::CAST, XDump, StringRecTy::get(Records));
+  if (CurRec)
+    CurRec->addAssertion(ConditionLoc, Condition, Message);
+  else
+    addEntry(std::make_unique<Record::AssertionInfo>(ConditionLoc, Condition,
+                                                     Message));
+  return false;
+}
+
 /// ParseClass - Parse a tblgen class definition.
 ///
 ///   ClassInst ::= CLASS ID TemplateArgList? ObjectBody
 ///
 bool TGParser::ParseClass() {
   assert(Lex.getCode() == tgtok::Class && "Unexpected token!");
   Lex.Lex();
 

 /// ParseMultiClass - Parse a multiclass definition.
 ///
 ///  MultiClassInst ::= MULTICLASS ID TemplateArgList?
 ///                     ':' BaseMultiClassList '{' MultiClassObject+ '}'
 ///  MultiClassObject ::= Assert
 ///  MultiClassObject ::= DefInst
 ///  MultiClassObject ::= DefMInst
 ///  MultiClassObject ::= Defvar
+///  MultiClassObject ::= Dump
 ///  MultiClassObject ::= Foreach
 ///  MultiClassObject ::= If
 ///  MultiClassObject ::= LETCommand '{' ObjectList '}'
 ///  MultiClassObject ::= LETCommand Object
 ///
 bool TGParser::ParseMultiClass() {
   assert(Lex.getCode() == tgtok::MultiClass && "Unexpected token");
   Lex.Lex();  // Eat the multiclass token.
bool TGParser::ParseMultiClass() {
   } else {
     if (Lex.Lex() == tgtok::r_brace)  // eat the '{'.
       return TokError("multiclass must contain at least one def");
 
     while (Lex.getCode() != tgtok::r_brace) {
       switch (Lex.getCode()) {
       default:
         return TokError("expected 'assert', 'def', 'defm', 'defvar', "
-                        "'foreach', 'if', or 'let' in multiclass body");
+                        "'foreach', 'if', 'dump', or 'let' in multiclass body");
 
       case tgtok::Assert:
       case tgtok::Def:
       case tgtok::Defm:
       case tgtok::Defvar:
       case tgtok::Foreach:
       case tgtok::If:
       case tgtok::Let:
+      case tgtok::Dump:
         if (ParseObject(CurMultiClass))
           return true;
         break;
       }
     }
     Lex.Lex();  // eat the '}'.
 
     // If we have a semicolon, print a gentle error.

 ///   Object ::= LETCommand '{' ObjectList '}'
 ///   Object ::= LETCommand Object
 ///   Object ::= Defset
 ///   Object ::= Defvar
 ///   Object ::= Assert
 bool TGParser::ParseObject(MultiClass *MC) {
   switch (Lex.getCode()) {
   default:
-    return TokError(
-               "Expected assert, class, def, defm, defset, foreach, if, or let");
+    return TokError("Expected assert, class, def, defm, defset, foreach, "
+                    "print, if, or let");
   case tgtok::Assert:  return ParseAssert(MC);
+  case tgtok::Dump:
+    return ParseDump(MC);
   case tgtok::Def:     return ParseDef(MC);
   case tgtok::Defm:    return ParseDefm(MC);
   case tgtok::Defvar:  return ParseDefvar();
   case tgtok::Foreach: return ParseForeach(MC);
   case tgtok::If:      return ParseIf(MC);
   case tgtok::Let:     return ParseTopLevelLet(MC);
   case tgtok::Defset:
     if (MC)

llvm/test/TableGen/dump.td

+// RUN: llvm-tblgen %s -o %t 2>&1 | FileCheck %s
+
+defvar a = 1111;
+defvar b = !add(!dump( a), 1);
+dump  b;
+// CHECK-LABEL: 1111
+// CHECK-LABEL: 1112
+
+class C<int i> {
+  int I = i;
+}
+def c: C<3>;
+dump c;
+// CHECK-LABEL: c { // C
+// CHECK-NEXT:     int I = 3;
+// CHECK-NEXT:  }
+
+dump C<5>;
+// CHECK-LABEL: anonymous_{{.*}} { // C
+// CHECK-NEXT:    int I = 5;
+// CHECK-NEXT:  }
+
+defvar lst = [C<1>, C<2>];
+dump lst;
+// CHECK-LABEL: [anonymous_{{.*}}, anonymous_{{.*}}]
+
+defvar p5 = !foreach(i, lst, !dump(i));
+// CHECK-LABEL: anonymous_{{.*}} { // C
+// CHECK-NEXT:    int I = 1;
+// CHECK-NEXT:  }
+// CHECK-LABEL: anonymous_{{.*}} { // C
+// CHECK-NEXT:    int I = 2;
+// CHECK-NEXT:  }
+
+foreach e = lst in {
+  dump  e;
+}
+// CHECK-LABEL: anonymous_{{.*}} { // C
+// CHECK-NEXT:    int I = 1;
+// CHECK-NEXT:  }
+// CHECK-LABEL: anonymous_{{.*}} { // C
+// CHECK-NEXT:    int I = 2;
+// CHECK-NEXT:  }
+
+class CC<int i> {
+  dump "i in CC<i> =";
+  dump  i;
+  int I = !add(i, 1);
+}
+def cc : CC<33>;
+// CHECK-LABEL: i in CC<i> =
+// CHECK-NEXT: 33
+
+class MCC<int i> {
+  int I = !add(i, 1);
+}
+multiclass MC<int i> {
+  dump "i in MCC<i> = ";
+  dump  i;
+  def : MCC<i>;
+}
+defm : MC<27>;
+// CHECK-LABEL: i in MCC<i> =
+// CHECK-NEXT: 27