1 //===- InstrDocsEmitter.cpp - Opcode Documentation Generator --------------===//
2 //
3 //                     The LLVM Compiler Infrastructure
4 //
5 // This file is distributed under the University of Illinois Open Source
6 // License. See LICENSE.TXT for details.
7 //
8 //===----------------------------------------------------------------------===//
9 //
10 // InstrDocsEmitter generates restructured text documentation for the opcodes
11 // that can be used by MachineInstr. For each opcode, the documentation lists:
12 // * Opcode name
13 // * Assembly string
14 // * Flags (e.g. mayLoad, isBranch, ...)
15 // * Operands, including type and name
16 // * Operand constraints
17 // * Implicit register uses & defs
18 // * Predicates
19 //
20 //===----------------------------------------------------------------------===//
21 
22 #include "CodeGenDAGPatterns.h"
23 #include "CodeGenInstruction.h"
24 #include "CodeGenTarget.h"
25 #include "TableGenBackends.h"
26 #include "llvm/TableGen/Record.h"
27 #include <string>
28 #include <vector>
29 
30 using namespace llvm;
31 
32 namespace llvm {
33 
34 void writeTitle(StringRef Str, raw_ostream &OS, char Kind = '-') {
35   OS << std::string(Str.size(), Kind) << "\n" << Str << "\n"
36      << std::string(Str.size(), Kind) << "\n";
37 }
38 
39 void writeHeader(StringRef Str, raw_ostream &OS, char Kind = '-') {
40   OS << Str << "\n" << std::string(Str.size(), Kind) << "\n";
41 }
42 
43 std::string escapeForRST(StringRef Str) {
44   std::string Result;
45   Result.reserve(Str.size() + 4);
46   for (char C : Str) {
47     switch (C) {
48     // We want special characters to be shown as their C escape codes.
49     case '\n': Result += "\\n"; break;
50     case '\t': Result += "\\t"; break;
51     // Underscore at the end of a line has a special meaning in rst.
52     case '_': Result += "\\_"; break;
53     default: Result += C;
54     }
55   }
56   return Result;
57 }
58 
59 void EmitInstrDocs(RecordKeeper &RK, raw_ostream &OS) {
60   CodeGenDAGPatterns CDP(RK);
61   CodeGenTarget &Target = CDP.getTargetInfo();
62   unsigned VariantCount = Target.getAsmParserVariantCount();
63 
64   // Page title.
65   std::string Title = Target.getName();
66   Title += " Instructions";
67   writeTitle(Title, OS);
68   OS << "\n";
69 
70   for (const CodeGenInstruction *II : Target.getInstructionsByEnumValue()) {
71     Record *Inst = II->TheDef;
72 
73     // Don't print the target-independent instructions.
74     if (II->Namespace == "TargetOpcode")
75       continue;
76 
77     // Heading (instruction name).
78     writeHeader(escapeForRST(Inst->getName()), OS, '=');
79     OS << "\n";
80 
81     // Assembly string(s).
82     if (!II->AsmString.empty()) {
83       for (unsigned VarNum = 0; VarNum < VariantCount; ++VarNum) {
84         Record *AsmVariant = Target.getAsmParserVariant(VarNum);
85         OS << "Assembly string";
86         if (VariantCount != 1)
87           OS << " (" << AsmVariant->getValueAsString("Name") << ")";
88         std::string AsmString =
89             CodeGenInstruction::FlattenAsmStringVariants(II->AsmString, VarNum);
90         // We trim spaces at each end of the asm string because rst needs the
91         // formatting backticks to be next to a non-whitespace character.
92         OS << ": ``" << escapeForRST(StringRef(AsmString).trim(" "))
93            << "``\n\n";
94       }
95     }
96 
97     // Boolean flags.
98     std::vector<const char *> FlagStrings;
99 #define xstr(s) str(s)
100 #define str(s) #s
101 #define FLAG(f) if (II->f) { FlagStrings.push_back(str(f)); }
102     FLAG(isReturn)
103     FLAG(isEHScopeReturn)
104     FLAG(isBranch)
105     FLAG(isIndirectBranch)
106     FLAG(isCompare)
107     FLAG(isMoveImm)
108     FLAG(isBitcast)
109     FLAG(isSelect)
110     FLAG(isBarrier)
111     FLAG(isCall)
112     FLAG(isAdd)
113     FLAG(isTrap)
114     FLAG(canFoldAsLoad)
115     FLAG(mayLoad)
116     //FLAG(mayLoad_Unset) // Deliberately omitted.
117     FLAG(mayStore)
118     //FLAG(mayStore_Unset) // Deliberately omitted.
119     FLAG(isPredicable)
120     FLAG(isConvertibleToThreeAddress)
121     FLAG(isCommutable)
122     FLAG(isTerminator)
123     FLAG(isReMaterializable)
124     FLAG(hasDelaySlot)
125     FLAG(usesCustomInserter)
126     FLAG(hasPostISelHook)
127     FLAG(hasCtrlDep)
128     FLAG(isNotDuplicable)
129     FLAG(hasSideEffects)
130     //FLAG(hasSideEffects_Unset) // Deliberately omitted.
131     FLAG(isAsCheapAsAMove)
132     FLAG(hasExtraSrcRegAllocReq)
133     FLAG(hasExtraDefRegAllocReq)
134     FLAG(isCodeGenOnly)
135     FLAG(isPseudo)
136     FLAG(isRegSequence)
137     FLAG(isExtractSubreg)
138     FLAG(isInsertSubreg)
139     FLAG(isConvergent)
140     FLAG(hasNoSchedulingInfo)
141     if (!FlagStrings.empty()) {
142       OS << "Flags: ";
143       bool IsFirst = true;
144       for (auto FlagString : FlagStrings) {
145         if (!IsFirst)
146           OS << ", ";
147         OS << "``" << FlagString << "``";
148         IsFirst = false;
149       }
150       OS << "\n\n";
151     }
152 
153     // Operands.
154     for (unsigned i = 0; i < II->Operands.size(); ++i) {
155       bool IsDef = i < II->Operands.NumDefs;
156       auto Op = II->Operands[i];
157 
158       if (Op.MINumOperands > 1) {
159         // This operand corresponds to multiple operands on the
160         // MachineInstruction, so print all of them, showing the types and
161         // names of both the compound operand and the basic operands it
162         // contains.
163         for (unsigned SubOpIdx = 0; SubOpIdx < Op.MINumOperands; ++SubOpIdx) {
164           Record *SubRec =
165               cast<DefInit>(Op.MIOperandInfo->getArg(SubOpIdx))->getDef();
166           StringRef SubOpName = Op.MIOperandInfo->getArgNameStr(SubOpIdx);
167           StringRef SubOpTypeName = SubRec->getName();
168 
169           OS << "* " << (IsDef ? "DEF" : "USE") << " ``" << Op.Rec->getName()
170              << "/" << SubOpTypeName << ":$" << Op.Name << ".";
171           // Not all sub-operands are named, make up a name for these.
172           if (SubOpName.empty())
173             OS << "anon" << SubOpIdx;
174           else
175             OS << SubOpName;
176           OS << "``\n\n";
177         }
178       } else {
179         // The operand corresponds to only one MachineInstruction operand.
180         OS << "* " << (IsDef ? "DEF" : "USE") << " ``" << Op.Rec->getName()
181            << ":$" << Op.Name << "``\n\n";
182       }
183     }
184 
185     // Constraints.
186     StringRef Constraints = Inst->getValueAsString("Constraints");
187     if (!Constraints.empty()) {
188       OS << "Constraints: ``" << Constraints << "``\n\n";
189     }
190 
191     // Implicit definitions.
192     if (!II->ImplicitDefs.empty()) {
193       OS << "Implicit defs: ";
194       bool IsFirst = true;
195       for (Record *Def : II->ImplicitDefs) {
196         if (!IsFirst)
197           OS << ", ";
198         OS << "``" << Def->getName() << "``";
199         IsFirst = false;
200       }
201       OS << "\n\n";
202     }
203 
204     // Implicit uses.
205     if (!II->ImplicitUses.empty()) {
206       OS << "Implicit uses: ";
207       bool IsFirst = true;
208       for (Record *Use : II->ImplicitUses) {
209         if (!IsFirst)
210           OS << ", ";
211         OS << "``" << Use->getName() << "``";
212         IsFirst = false;
213       }
214       OS << "\n\n";
215     }
216 
217     // Predicates.
218     std::vector<Record *> Predicates =
219         II->TheDef->getValueAsListOfDefs("Predicates");
220     if (!Predicates.empty()) {
221       OS << "Predicates: ";
222       bool IsFirst = true;
223       for (Record *P : Predicates) {
224         if (!IsFirst)
225           OS << ", ";
226         OS << "``" << P->getName() << "``";
227         IsFirst = false;
228       }
229       OS << "\n\n";
230     }
231   }
232 }
233 
234 } // end llvm namespace
235