1//===- X86DisassemblerTables.h - Disassembler tables ------------*- C++ -*-===//
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// This file is part of the X86 Disassembler Emitter.
10// It contains the interface of the disassembler tables.
11// Documentation for the disassembler emitter in general can be found in
12//  X86DisassemblerEmitter.h.
13//
14//===----------------------------------------------------------------------===//
15
16#ifndef LLVM_UTILS_TABLEGEN_X86DISASSEMBLERTABLES_H
17#define LLVM_UTILS_TABLEGEN_X86DISASSEMBLERTABLES_H
18
19#include "X86DisassemblerShared.h"
20#include "X86ModRMFilters.h"
21#include "llvm/Support/raw_ostream.h"
22#include <map>
23#include <vector>
24
25namespace llvm {
26
27namespace X86Disassembler {
28
29/// DisassemblerTables - Encapsulates all the decode tables being generated by
30///   the table emitter.  Contains functions to populate the tables as well as
31///   to emit them as hierarchical C structures suitable for consumption by the
32///   runtime.
33class DisassemblerTables {
34private:
35  /// The decoder tables.  There is one for each opcode type:
36  /// [0] one-byte opcodes
37  /// [1] two-byte opcodes of the form 0f __
38  /// [2] three-byte opcodes of the form 0f 38 __
39  /// [3] three-byte opcodes of the form 0f 3a __
40  /// [4] XOP8 map opcode
41  /// [5] XOP9 map opcode
42  /// [6] XOPA map opcode
43  /// [7] 3dnow map opcode
44  std::unique_ptr<ContextDecision> Tables[8];
45
46  // Table of ModRM encodings.
47  typedef std::map<std::vector<unsigned>, unsigned> ModRMMapTy;
48  mutable ModRMMapTy ModRMTable;
49
50  /// The instruction information table
51  std::vector<InstructionSpecifier> InstructionSpecifiers;
52
53  /// True if there are primary decode conflicts in the instruction set
54  bool HasConflicts;
55
56  /// emitModRMDecision - Emits a table of entries corresponding to a single
57  ///   ModR/M decision.  Compacts the ModR/M decision if possible.  ModR/M
58  ///   decisions are printed as:
59  ///
60  ///   { /* struct ModRMDecision */
61  ///     TYPE,
62  ///     modRMTablennnn
63  ///   }
64  ///
65  ///   where nnnn is a unique ID for the corresponding table of IDs.
66  ///   TYPE indicates whether the table has one entry that is the same
67  ///   regardless of ModR/M byte, two entries - one for bytes 0x00-0xbf and one
68  ///   for bytes 0xc0-0xff -, or 256 entries, one for each possible byte.
69  ///   nnnn is the number of a table for looking up these values.  The tables
70  ///   are written separately so that tables consisting entirely of zeros will
71  ///   not be duplicated.  (These all have the name modRMEmptyTable.)  A table
72  ///   is printed as:
73  ///
74  ///   InstrUID modRMTablennnn[k] = {
75  ///     nnnn, /* MNEMONIC */
76  ///     ...
77  ///     nnnn /* MNEMONIC */
78  ///   };
79  ///
80  /// @param o1       - The output stream to print the ID table to.
81  /// @param o2       - The output stream to print the decision structure to.
82  /// @param i1       - The indentation level to use with stream o1.
83  /// @param i2       - The indentation level to use with stream o2.
84  /// @param ModRMTableNum - next table number for adding to ModRMTable.
85  /// @param decision - The ModR/M decision to emit.  This decision has 256
86  ///                   entries - emitModRMDecision decides how to compact it.
87  void emitModRMDecision(raw_ostream &o1, raw_ostream &o2,
88                         unsigned &i1, unsigned &i2, unsigned &ModRMTableNum,
89                         ModRMDecision &decision) const;
90
91  /// emitOpcodeDecision - Emits an OpcodeDecision and all its subsidiary ModR/M
92  ///   decisions.  An OpcodeDecision is printed as:
93  ///
94  ///   { /* struct OpcodeDecision */
95  ///     /* 0x00 */
96  ///     { /* struct ModRMDecision */
97  ///       ...
98  ///     }
99  ///     ...
100  ///   }
101  ///
102  ///   where the ModRMDecision structure is printed as described in the
103  ///   documentation for emitModRMDecision().  emitOpcodeDecision() passes on a
104  ///   stream and indent level for the UID tables generated by
105  ///   emitModRMDecision(), but does not use them itself.
106  ///
107  /// @param o1       - The output stream to print the ID tables generated by
108  ///                   emitModRMDecision() to.
109  /// @param o2       - The output stream for the decision structure itself.
110  /// @param i1       - The indent level to use with stream o1.
111  /// @param i2       - The indent level to use with stream o2.
112  /// @param ModRMTableNum - next table number for adding to ModRMTable.
113  /// @param decision - The OpcodeDecision to emit along with its subsidiary
114  ///                    structures.
115  void emitOpcodeDecision(raw_ostream &o1, raw_ostream &o2,
116                          unsigned &i1, unsigned &i2, unsigned &ModRMTableNum,
117                          OpcodeDecision &decision) const;
118
119  /// emitContextDecision - Emits a ContextDecision and all its subsidiary
120  ///   Opcode and ModRMDecisions.  A ContextDecision is printed as:
121  ///
122  ///   struct ContextDecision NAME = {
123  ///     { /* OpcodeDecisions */
124  ///       /* IC */
125  ///       { /* struct OpcodeDecision */
126  ///         ...
127  ///       },
128  ///       ...
129  ///     }
130  ///   }
131  ///
132  ///   NAME is the name of the ContextDecision (typically one of the four names
133  ///   ONEBYTE_SYM, TWOBYTE_SYM, THREEBYTE38_SYM, THREEBYTE3A_SYM from
134  ///   X86DisassemblerDecoderCommon.h).
135  ///   IC is one of the contexts in InstructionContext.  There is an opcode
136  ///   decision for each possible context.
137  ///   The OpcodeDecision structures are printed as described in the
138  ///   documentation for emitOpcodeDecision.
139  ///
140  /// @param o1       - The output stream to print the ID tables generated by
141  ///                   emitModRMDecision() to.
142  /// @param o2       - The output stream to print the decision structure to.
143  /// @param i1       - The indent level to use with stream o1.
144  /// @param i2       - The indent level to use with stream o2.
145  /// @param ModRMTableNum - next table number for adding to ModRMTable.
146  /// @param decision - The ContextDecision to emit along with its subsidiary
147  ///                   structures.
148  /// @param name     - The name for the ContextDecision.
149  void emitContextDecision(raw_ostream &o1, raw_ostream &o2,
150                           unsigned &i1, unsigned &i2, unsigned &ModRMTableNum,
151                           ContextDecision &decision, const char* name) const;
152
153  /// emitInstructionInfo - Prints the instruction specifier table, which has
154  ///   one entry for each instruction, and contains name and operand
155  ///   information.  This table is printed as:
156  ///
157  ///   struct InstructionSpecifier CONTEXTS_SYM[k] = {
158  ///     {
159  ///       /* nnnn */
160  ///       "MNEMONIC",
161  ///       0xnn,
162  ///       {
163  ///         {
164  ///           ENCODING,
165  ///           TYPE
166  ///         },
167  ///         ...
168  ///       }
169  ///     },
170  ///   };
171  ///
172  ///   k is the total number of instructions.
173  ///   nnnn is the ID of the current instruction (0-based).  This table
174  ///   includes entries for non-instructions like PHINODE.
175  ///   0xnn is the lowest possible opcode for the current instruction, used for
176  ///   AddRegFrm instructions to compute the operand's value.
177  ///   ENCODING and TYPE describe the encoding and type for a single operand.
178  ///
179  /// @param o  - The output stream to which the instruction table should be
180  ///             written.
181  /// @param i  - The indent level for use with the stream.
182  void emitInstructionInfo(raw_ostream &o, unsigned &i) const;
183
184  /// emitContextTable - Prints the table that is used to translate from an
185  ///   instruction attribute mask to an instruction context.  This table is
186  ///   printed as:
187  ///
188  ///   InstructionContext CONTEXTS_STR[256] = {
189  ///     IC, /* 0x00 */
190  ///     ...
191  ///   };
192  ///
193  ///   IC is the context corresponding to the mask 0x00, and there are 256
194  ///   possible masks.
195  ///
196  /// @param o  - The output stream to which the context table should be written.
197  /// @param i  - The indent level for use with the stream.
198  void emitContextTable(raw_ostream &o, uint32_t &i) const;
199
200  /// emitContextDecisions - Prints all four ContextDecision structures using
201  ///   emitContextDecision().
202  ///
203  /// @param o1 - The output stream to print the ID tables generated by
204  ///             emitModRMDecision() to.
205  /// @param o2 - The output stream to print the decision structures to.
206  /// @param i1 - The indent level to use with stream o1.
207  /// @param i2 - The indent level to use with stream o2.
208  /// @param ModRMTableNum - next table number for adding to ModRMTable.
209  void emitContextDecisions(raw_ostream &o1, raw_ostream &o2,
210                            unsigned &i1, unsigned &i2,
211                            unsigned &ModRMTableNum) const;
212
213  /// setTableFields - Uses a ModRMFilter to set the appropriate entries in a
214  ///   ModRMDecision to refer to a particular instruction ID.
215  ///
216  /// @param decision - The ModRMDecision to populate.
217  /// @param filter   - The filter to use in deciding which entries to populate.
218  /// @param uid      - The unique ID to set matching entries to.
219  /// @param opcode   - The opcode of the instruction, for error reporting.
220  void setTableFields(ModRMDecision &decision,
221                      const ModRMFilter &filter,
222                      InstrUID uid,
223                      uint8_t opcode);
224public:
225  /// Constructor - Allocates space for the class decisions and clears them.
226  DisassemblerTables();
227
228  ~DisassemblerTables();
229
230  /// emit - Emits the instruction table, context table, and class decisions.
231  ///
232  /// @param o  - The output stream to print the tables to.
233  void emit(raw_ostream &o) const;
234
235  /// setTableFields - Uses the opcode type, instruction context, opcode, and a
236  ///   ModRMFilter as criteria to set a particular set of entries in the
237  ///   decode tables to point to a specific uid.
238  ///
239  /// @param type         - The opcode type (ONEBYTE, TWOBYTE, etc.)
240  /// @param insnContext  - The context to use (IC, IC_64BIT, etc.)
241  /// @param opcode       - The last byte of the opcode (not counting any escape
242  ///                       or extended opcodes).
243  /// @param filter       - The ModRMFilter that decides which ModR/M byte values
244  ///                       correspond to the desired instruction.
245  /// @param uid          - The unique ID of the instruction.
246  /// @param is32bit      - Instructon is only 32-bit
247  /// @param noPrefix     - Instruction record has no prefix.
248  /// @param ignoresVEX_L - Instruction ignores VEX.L
249  /// @param ignoresVEX_W - Instruction ignores VEX.W
250  /// @param AddrSize     - Instructions address size 16/32/64. 0 is unspecified
251  void setTableFields(OpcodeType type,
252                      InstructionContext insnContext,
253                      uint8_t opcode,
254                      const ModRMFilter &filter,
255                      InstrUID uid,
256                      bool is32bit,
257                      bool noPrefix,
258                      bool ignoresVEX_L,
259                      bool ignoresVEX_W,
260                      unsigned AddrSize);
261
262  /// specForUID - Returns the instruction specifier for a given unique
263  ///   instruction ID.  Used when resolving collisions.
264  ///
265  /// @param uid  - The unique ID of the instruction.
266  /// @return     - A reference to the instruction specifier.
267  InstructionSpecifier& specForUID(InstrUID uid) {
268    if (uid >= InstructionSpecifiers.size())
269      InstructionSpecifiers.resize(uid + 1);
270
271    return InstructionSpecifiers[uid];
272  }
273
274  // hasConflicts - Reports whether there were primary decode conflicts
275  //   from any instructions added to the tables.
276  // @return  - true if there were; false otherwise.
277
278  bool hasConflicts() {
279    return HasConflicts;
280  }
281};
282
283} // namespace X86Disassembler
284
285} // namespace llvm
286
287#endif
288