1//===- DisassemblerEmitter.cpp - Generate a disassembler ------------------===//
2//
3// Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
4// See https://llvm.org/LICENSE.txt for license information.
5// SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
6//
7//===----------------------------------------------------------------------===//
8
9#include "Common/CodeGenTarget.h"
10#include "TableGenBackends.h"
11#include "WebAssemblyDisassemblerEmitter.h"
12#include "X86DisassemblerTables.h"
13#include "X86RecognizableInstr.h"
14#include "llvm/Support/CommandLine.h"
15#include "llvm/TableGen/Error.h"
16#include "llvm/TableGen/Record.h"
17#include "llvm/TableGen/TableGenBackend.h"
18
19using namespace llvm;
20using namespace llvm::X86Disassembler;
21
22/// DisassemblerEmitter - Contains disassembler table emitters for various
23/// architectures.
24
25/// X86 Disassembler Emitter
26///
27/// *** IF YOU'RE HERE TO RESOLVE A "Primary decode conflict", LOOK DOWN NEAR
28/// THE END OF THIS COMMENT!
29///
30/// The X86 disassembler emitter is part of the X86 Disassembler, which is
31/// documented in lib/Target/X86/X86Disassembler.h.
32///
33/// The emitter produces the tables that the disassembler uses to translate
34/// instructions. The emitter generates the following tables:
35///
36/// - One table (CONTEXTS_SYM) that contains a mapping of attribute masks to
37/// instruction contexts. Although for each attribute there are cases where
38/// that attribute determines decoding, in the majority of cases decoding is
39/// the same whether or not an attribute is present. For example, a 64-bit
40/// instruction with an OPSIZE prefix and an XS prefix decodes the same way in
41/// all cases as a 64-bit instruction with only OPSIZE set. (The XS prefix
42/// may have effects on its execution, but does not change the instruction
43/// returned.) This allows considerable space savings in other tables.
44/// - The common opcode maps use direct context tables. The remaining sparse
45/// maps share unique rows in SPARSE_OPCODE_DECISIONS_SYM, with
46/// SPARSE_OPCODE_DECISION_INDICES_SYM mapping each sparse map and instruction
47/// context to a row. At the lowest level of this hierarchy are instruction
48/// UIDs, 16-bit integers that can be used to uniquely identify the
49/// instruction and correspond exactly to its position in the list of
50/// CodeGenInstructions for the target.
51/// - One table (INSTRUCTIONS_SYM) contains information about the operands of
52/// each instruction and how to decode them.
53///
54/// During table generation, there may be conflicts between instructions that
55/// occupy the same space in the decode tables. These conflicts are resolved as
56/// follows in setTableFields() (X86DisassemblerTables.cpp)
57///
58/// - If the current context is the native context for one of the instructions
59/// (that is, the attributes specified for it in the LLVM tables specify
60/// precisely the current context), then it has priority.
61/// - If the current context isn't native for either of the instructions, then
62/// the higher-priority context wins (that is, the one that is more specific).
63/// That hierarchy is determined by outranks() (X86DisassemblerTables.cpp)
64/// - If the current context is native for both instructions, then the table
65/// emitter reports a conflict and dies.
66///
67/// *** RESOLUTION FOR "Primary decode conflict"S
68///
69/// If two instructions collide, typically the solution is (in order of
70/// likelihood):
71///
72/// (1) to filter out one of the instructions by editing filter()
73/// (X86RecognizableInstr.cpp). This is the most common resolution, but
74/// check the Intel manuals first to make sure that (2) and (3) are not the
75/// problem.
76/// (2) to fix the tables (X86.td and its subsidiaries) so the opcodes are
77/// accurate. Sometimes they are not.
78/// (3) to fix the tables to reflect the actual context (for example, required
79/// prefixes), and possibly to add a new context by editing
80/// include/llvm/Support/X86DisassemblerDecoderCommon.h. This is unlikely
81/// to be the cause.
82///
83/// DisassemblerEmitter.cpp contains the implementation for the emitter,
84/// which simply pulls out instructions from the CodeGenTarget and pushes them
85/// into X86DisassemblerTables.
86/// X86DisassemblerTables.h contains the interface for the instruction tables,
87/// which manage and emit the structures discussed above.
88/// X86DisassemblerTables.cpp contains the implementation for the instruction
89/// tables.
90/// X86ModRMFilters.h contains filters that can be used to determine which
91/// ModR/M values are valid for a particular instruction. These are used to
92/// populate ModRMDecisions.
93/// X86RecognizableInstr.h contains the interface for a single instruction,
94/// which knows how to translate itself from a CodeGenInstruction and provide
95/// the information necessary for integration into the tables.
96/// X86RecognizableInstr.cpp contains the implementation for a single
97/// instruction.
98
99static void emitDisassembler(const RecordKeeper &Records, raw_ostream &OS) {
100 const CodeGenTarget Target(Records);
101 emitSourceFileHeader(Desc: " * " + Target.getName().str() + " Disassembler", OS);
102
103 // X86 uses a custom disassembler.
104 if (Target.getName() == "X86") {
105 DisassemblerTables Tables;
106
107 for (const auto &[Idx, NumberedInst] : enumerate(First: Target.getInstructions()))
108 RecognizableInstr::processInstr(tables&: Tables, insn: *NumberedInst, uid: Idx);
109
110 if (Tables.hasConflicts()) {
111 PrintError(ErrorLoc: Target.getTargetRecord()->getLoc(), Msg: "Primary decode conflict");
112 return;
113 }
114
115 Tables.emit(o&: OS);
116 return;
117 }
118
119 // WebAssembly has variable length opcodes, so can't use EmitFixedLenDecoder
120 // below (which depends on a Size table-gen Record), and also uses a custom
121 // disassembler.
122 if (Target.getName() == "WebAssembly") {
123 emitWebAssemblyDisassemblerTables(OS, NumberedInstructions: Target.getInstructions());
124 return;
125 }
126
127 EmitDecoder(RK: Records, OS);
128}
129
130cl::OptionCategory DisassemblerEmitterCat("Options for -gen-disassembler");
131
132static TableGen::Emitter::Opt X("gen-disassembler", emitDisassembler,
133 "Generate disassembler");
134