blob: bc391227edd1616e17b1b33f14eea82e940c030a [file] [log] [blame]
//===- InstrDocsEmitter.cpp - Opcode Documentation Generator --------------===//
//
// Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
// See https://llvm.org/LICENSE.txt for license information.
// SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
//
//===----------------------------------------------------------------------===//
//
// InstrDocsEmitter generates restructured text documentation for the opcodes
// that can be used by MachineInstr. For each opcode, the documentation lists:
// * Opcode name
// * Assembly string
// * Flags (e.g. mayLoad, isBranch, ...)
// * Operands, including type and name
// * Operand constraints
// * Implicit register uses & defs
// * Predicates
//
//===----------------------------------------------------------------------===//
#include "CodeGenDAGPatterns.h"
#include "CodeGenInstruction.h"
#include "CodeGenTarget.h"
#include "TableGenBackends.h"
#include "llvm/TableGen/Record.h"
#include <string>
#include <vector>
using namespace llvm;
namespace llvm {
void writeTitle(StringRef Str, raw_ostream &OS, char Kind = '-') {
OS << std::string(Str.size(), Kind) << "\n" << Str << "\n"
<< std::string(Str.size(), Kind) << "\n";
}
void writeHeader(StringRef Str, raw_ostream &OS, char Kind = '-') {
OS << Str << "\n" << std::string(Str.size(), Kind) << "\n";
}
std::string escapeForRST(StringRef Str) {
std::string Result;
Result.reserve(Str.size() + 4);
for (char C : Str) {
switch (C) {
// We want special characters to be shown as their C escape codes.
case '\n': Result += "\\n"; break;
case '\t': Result += "\\t"; break;
// Underscore at the end of a line has a special meaning in rst.
case '_': Result += "\\_"; break;
default: Result += C;
}
}
return Result;
}
void EmitInstrDocs(RecordKeeper &RK, raw_ostream &OS) {
CodeGenDAGPatterns CDP(RK);
CodeGenTarget &Target = CDP.getTargetInfo();
unsigned VariantCount = Target.getAsmParserVariantCount();
// Page title.
std::string Title = std::string(Target.getName());
Title += " Instructions";
writeTitle(Title, OS);
OS << "\n";
for (const CodeGenInstruction *II : Target.getInstructionsByEnumValue()) {
Record *Inst = II->TheDef;
// Don't print the target-independent instructions.
if (II->Namespace == "TargetOpcode")
continue;
// Heading (instruction name).
writeHeader(escapeForRST(Inst->getName()), OS, '=');
OS << "\n";
// Assembly string(s).
if (!II->AsmString.empty()) {
for (unsigned VarNum = 0; VarNum < VariantCount; ++VarNum) {
Record *AsmVariant = Target.getAsmParserVariant(VarNum);
OS << "Assembly string";
if (VariantCount != 1)
OS << " (" << AsmVariant->getValueAsString("Name") << ")";
std::string AsmString =
CodeGenInstruction::FlattenAsmStringVariants(II->AsmString, VarNum);
// We trim spaces at each end of the asm string because rst needs the
// formatting backticks to be next to a non-whitespace character.
OS << ": ``" << escapeForRST(StringRef(AsmString).trim(" "))
<< "``\n\n";
}
}
// Boolean flags.
std::vector<const char *> FlagStrings;
#define xstr(s) str(s)
#define str(s) #s
#define FLAG(f) if (II->f) { FlagStrings.push_back(str(f)); }
FLAG(isReturn)
FLAG(isEHScopeReturn)
FLAG(isBranch)
FLAG(isIndirectBranch)
FLAG(isCompare)
FLAG(isMoveImm)
FLAG(isBitcast)
FLAG(isSelect)
FLAG(isBarrier)
FLAG(isCall)
FLAG(isAdd)
FLAG(isTrap)
FLAG(canFoldAsLoad)
FLAG(mayLoad)
//FLAG(mayLoad_Unset) // Deliberately omitted.
FLAG(mayStore)
//FLAG(mayStore_Unset) // Deliberately omitted.
FLAG(isPredicable)
FLAG(isConvertibleToThreeAddress)
FLAG(isCommutable)
FLAG(isTerminator)
FLAG(isReMaterializable)
FLAG(hasDelaySlot)
FLAG(usesCustomInserter)
FLAG(hasPostISelHook)
FLAG(hasCtrlDep)
FLAG(isNotDuplicable)
FLAG(hasSideEffects)
//FLAG(hasSideEffects_Unset) // Deliberately omitted.
FLAG(isAsCheapAsAMove)
FLAG(hasExtraSrcRegAllocReq)
FLAG(hasExtraDefRegAllocReq)
FLAG(isCodeGenOnly)
FLAG(isPseudo)
FLAG(isRegSequence)
FLAG(isExtractSubreg)
FLAG(isInsertSubreg)
FLAG(isConvergent)
FLAG(hasNoSchedulingInfo)
FLAG(variadicOpsAreDefs)
FLAG(isAuthenticated)
if (!FlagStrings.empty()) {
OS << "Flags: ";
ListSeparator LS;
for (auto FlagString : FlagStrings)
OS << LS << "``" << FlagString << "``";
OS << "\n\n";
}
// Operands.
for (unsigned i = 0; i < II->Operands.size(); ++i) {
bool IsDef = i < II->Operands.NumDefs;
auto Op = II->Operands[i];
if (Op.MINumOperands > 1) {
// This operand corresponds to multiple operands on the
// MachineInstruction, so print all of them, showing the types and
// names of both the compound operand and the basic operands it
// contains.
for (unsigned SubOpIdx = 0; SubOpIdx < Op.MINumOperands; ++SubOpIdx) {
Record *SubRec =
cast<DefInit>(Op.MIOperandInfo->getArg(SubOpIdx))->getDef();
StringRef SubOpName = Op.MIOperandInfo->getArgNameStr(SubOpIdx);
StringRef SubOpTypeName = SubRec->getName();
OS << "* " << (IsDef ? "DEF" : "USE") << " ``" << Op.Rec->getName()
<< "/" << SubOpTypeName << ":$" << Op.Name << ".";
// Not all sub-operands are named, make up a name for these.
if (SubOpName.empty())
OS << "anon" << SubOpIdx;
else
OS << SubOpName;
OS << "``\n\n";
}
} else {
// The operand corresponds to only one MachineInstruction operand.
OS << "* " << (IsDef ? "DEF" : "USE") << " ``" << Op.Rec->getName()
<< ":$" << Op.Name << "``\n\n";
}
}
// Constraints.
StringRef Constraints = Inst->getValueAsString("Constraints");
if (!Constraints.empty()) {
OS << "Constraints: ``" << Constraints << "``\n\n";
}
// Implicit definitions.
if (!II->ImplicitDefs.empty()) {
OS << "Implicit defs: ";
ListSeparator LS;
for (Record *Def : II->ImplicitDefs)
OS << LS << "``" << Def->getName() << "``";
OS << "\n\n";
}
// Implicit uses.
if (!II->ImplicitUses.empty()) {
OS << "Implicit uses: ";
ListSeparator LS;
for (Record *Use : II->ImplicitUses)
OS << LS << "``" << Use->getName() << "``";
OS << "\n\n";
}
// Predicates.
std::vector<Record *> Predicates =
II->TheDef->getValueAsListOfDefs("Predicates");
if (!Predicates.empty()) {
OS << "Predicates: ";
ListSeparator LS;
for (Record *P : Predicates)
OS << LS << "``" << P->getName() << "``";
OS << "\n\n";
}
}
}
} // end namespace llvm