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/// - Six tables (ONEBYTE_SYM, TWOBYTE_SYM, THREEBYTE38_SYM, THREEBYTE3A_SYM,
45/// THREEBYTEA6_SYM, and THREEBYTEA7_SYM contain the hierarchy that the
46/// decoder traverses while decoding an instruction. At the lowest level of
47/// this hierarchy are instruction UIDs, 16-bit integers that can be used to
48/// uniquely identify the instruction and correspond exactly to its position
49/// in the list of CodeGenInstructions for the target.
50/// - One table (INSTRUCTIONS_SYM) contains information about the operands of
51/// each instruction and how to decode them.
52///
53/// During table generation, there may be conflicts between instructions that
54/// occupy the same space in the decode tables. These conflicts are resolved as
55/// follows in setTableFields() (X86DisassemblerTables.cpp)
56///
57/// - If the current context is the native context for one of the instructions
58/// (that is, the attributes specified for it in the LLVM tables specify
59/// precisely the current context), then it has priority.
60/// - If the current context isn't native for either of the instructions, then
61/// the higher-priority context wins (that is, the one that is more specific).
62/// That hierarchy is determined by outranks() (X86DisassemblerTables.cpp)
63/// - If the current context is native for both instructions, then the table
64/// emitter reports a conflict and dies.
65///
66/// *** RESOLUTION FOR "Primary decode conflict"S
67///
68/// If two instructions collide, typically the solution is (in order of
69/// likelihood):
70///
71/// (1) to filter out one of the instructions by editing filter()
72/// (X86RecognizableInstr.cpp). This is the most common resolution, but
73/// check the Intel manuals first to make sure that (2) and (3) are not the
74/// problem.
75/// (2) to fix the tables (X86.td and its subsidiaries) so the opcodes are
76/// accurate. Sometimes they are not.
77/// (3) to fix the tables to reflect the actual context (for example, required
78/// prefixes), and possibly to add a new context by editing
79/// include/llvm/Support/X86DisassemblerDecoderCommon.h. This is unlikely
80/// to be the cause.
81///
82/// DisassemblerEmitter.cpp contains the implementation for the emitter,
83/// which simply pulls out instructions from the CodeGenTarget and pushes them
84/// into X86DisassemblerTables.
85/// X86DisassemblerTables.h contains the interface for the instruction tables,
86/// which manage and emit the structures discussed above.
87/// X86DisassemblerTables.cpp contains the implementation for the instruction
88/// tables.
89/// X86ModRMFilters.h contains filters that can be used to determine which
90/// ModR/M values are valid for a particular instruction. These are used to
91/// populate ModRMDecisions.
92/// X86RecognizableInstr.h contains the interface for a single instruction,
93/// which knows how to translate itself from a CodeGenInstruction and provide
94/// the information necessary for integration into the tables.
95/// X86RecognizableInstr.cpp contains the implementation for a single
96/// instruction.
97
98static void emitDisassembler(const RecordKeeper &Records, raw_ostream &OS) {
99 const CodeGenTarget Target(Records);
100 emitSourceFileHeader(Desc: " * " + Target.getName().str() + " Disassembler", OS);
101
102 // X86 uses a custom disassembler.
103 if (Target.getName() == "X86") {
104 DisassemblerTables Tables;
105
106 for (const auto &[Idx, NumberedInst] :
107 enumerate(First: Target.getInstructionsByEnumValue()))
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.getInstructionsByEnumValue());
124 return;
125 }
126
127 StringRef PredicateNamespace = Target.getName();
128 if (PredicateNamespace == "Thumb")
129 PredicateNamespace = "ARM";
130 EmitDecoder(RK: Records, OS, PredicateNamespace);
131}
132
133cl::OptionCategory DisassemblerEmitterCat("Options for -gen-disassembler");
134
135static TableGen::Emitter::Opt X("gen-disassembler", emitDisassembler,
136 "Generate disassembler");
137