Debian Codegraph @

opcodes/x86_64.py

raw ◀ ▶
1 Debian patch touch this file
1 from __future__ import print_function
2 import xml.etree.ElementTree as ET
3
•4 from importlib.resources import files
5
6 class Instruction:
7 """Instruction is defined by its mnemonic name (in Intel-style assembly).
8
9 An instruction may have multiple forms, that mainly differ by operand types.
10
11 :ivar name: instruction name in Intel-style assembly (PeachPy, NASM and YASM assemblers).
12 :ivar summary: a summary description of the instruction name.
13 :ivar forms: a list of :class:`InstructionForm` objects representing the instruction forms.
14 """
15 def __init__(self, name):
16 self.name = name
17 self.summary = None
18 self.forms = []
19
20 def __str__(self):
21 """Returns string representation of the instruction and the number of instruction forms"""
22 return "%s (%d forms)" % (self.name, len(self.forms))
23
24 def __repr__(self):
25 return str(self)
26
27
28 class InstructionForm:
29 """Instruction form is a combination of mnemonic name and operand types.
30
31 An instruction form may have multiple possible encodings.
32
33 :ivar name: instruction name in PeachPy, NASM and YASM assemblers.
34 :ivar gas_name: instruction form name in GNU assembler (gas).
35 :ivar go_name: instruction form name in Go/Plan 9 assembler (8a).
36
37 None means instruction is not supported in Go/Plan 9 assembler.
38
39 :ivar mmx_mode: MMX technology state required or forced by this instruction. Possible values are:
40
41 "FPU"
42 Instruction requires the MMX technology state to be clear.
43
44 "MMX"
45 Instruction causes transition to MMX technology state.
46
47 None
48 Instruction neither affects nor cares about the MMX technology state.
49
50 :ivar xmm_mode: XMM registers state accessed by this instruction. Possible values are:
51
52 "SSE"
53 Instruction accesses XMM registers in legacy SSE mode.
54
55 "AVX"
56 Instruction accesses XMM registers in AVX mode.
57
58 None
59 Instruction does not affect XMM registers and does not change XMM registers access mode.
60
61 :ivar cancelling_inputs: indicates that the instruction form has not dependency on the values of input operands
62 when they refer to the same register. E.g. **VPXOR xmm1, xmm0, xmm0** does not depend on *xmm0*.
63
64 Instruction forms with cancelling inputs have only two input operands, which have the same register type.
65
66 :ivar nacl_version: indicates the earliest Pepper API version where validator supports this instruction.
67
68 Possible values are integers >= 33 or None. Pepper 33 is the earliest version for which information on
69 supported instructions is available; if instruction forms supported before Pepper 33 would have
70 nacl_version == 33. None means instruction is either not yet supported by Native Client validator, or
71 is forbidden in Native Client SFI model.
72
73 :ivar nacl_zero_extends_outputs: indicates that Native Client validator recognizes that the instruction zeroes
74 the upper 32 bits of the output registers.
75
76 In x86-64 Native Client SFI model this means that the subsequent instruction can use registers written by
77 this instruction for memory addressing.
78
79 :ivar operands: a list of :class:`Operand` objects representing the instruction operands.
80 :ivar implicit_inputs: a set of register names that are implicitly read by this instruction.
81 :ivar implicit_outputs: a set of register names that are implicitly written by this instruction.
82 :ivar isa_extensions: a list of :class:`ISAExtension` objects that represent the ISA extensions required to execute
83 the instruction.
84 :ivar encodings: a list of :class:`Encoding` objects representing the possible encodings for this instruction.
85 """
86
87 def __init__(self, name):
88 self.name = name
89 self.gas_name = None
90 self.go_name = None
91 self.mmx_mode = None
92 self.xmm_mode = None
93 self.cancelling_inputs = None
94 self.nacl_version = None
95 self.nacl_zero_extends_outputs = None
96 self.operands = []
97 self.implicit_inputs = set()
98 self.implicit_outputs = set()
99 self.isa_extensions = []
100 self.encodings = []
101
102 def __str__(self):
103 """Returns string representation of the instruction form and its operands in Intel-style assembly"""
104 if self.operands:
105 return self.name + " " + ", ".join(operand.type for operand in self.operands)
106 else:
107 return self.name
108
109 def __repr__(self):
110 return str(self)
111
112
113 class Operand:
114 """An explicit instruction operand.
115
116 :ivar type: the type of the instruction operand. Possible values are:
117
118 "1"
119 The constant value `1`.
120
121 "3"
122 The constant value `3`.
123
124 "al"
125 The al register.
126
127 "ax"
128 The ax register.
129
130 "eax"
131 The eax register.
132
133 "rax"
134 The rax register.
135
136 "cl"
137 The cl register.
138
139 "xmm0"
140 The xmm0 register.
141
142 "rel8"
143 An 8-bit signed offset relative to the address of instruction end.
144
145 "rel32"
146 A 32-bit signed offset relative to the address of instruction end.
147
148 "imm4"
149 A 4-bit immediate value.
150
151 "imm8"
152 An 8-bit immediate value.
153
154 "imm16"
155 A 16-bit immediate value.
156
157 "imm32"
158 A 32-bit immediate value.
159
160 "imm64"
161 A 64-bit immediate value.
162
163 "r8"
164 An 8-bit general-purpose register (al, bl, cl, dl, sil, dil, bpl, spl, r8b-r15b).
165
166 "r16"
167 A 16-bit general-purpose register (ax, bx, cx, dx, si, di, bp, sp, r8w-r15w).
168
169 "r32"
170 A 32-bit general-purpose register (eax, ebx, ecx, edx, esi, edi, ebp, esp, r8d-r15d).
171
172 "r64"
173 A 64-bit general-purpose register (rax, rbx, rcx, rdx, rsi, rdi, rbp, rsp, r8-r15).
174
175 "mm"
176 A 64-bit MMX SIMD register (mm0-mm7).
177
178 "xmm"
179 A 128-bit XMM SIMD register (xmm0-xmm31).
180
181 "xmm{k}"
182 A 128-bit XMM SIMD register (xmm0-xmm31), optionally merge-masked by an AVX-512 mask register (k1-k7).
183
184 "xmm{k}{z}"
185 A 128-bit XMM SIMD register (xmm0-xmm31), optionally masked by an AVX-512 mask register (k1-k7).
186
187 "ymm"
188 A 256-bit YMM SIMD register (ymm0-ymm31).
189
190 "ymm{k}"
191 A 256-bit YMM SIMD register (ymm0-ymm31), optionally merge-masked by an AVX-512 mask register (k1-k7).
192
193 "ymm{k}{z}"
194 A 256-bit YMM SIMD register (ymm0-ymm31), optionally masked by an AVX-512 mask register (k1-k7).
195
196 "zmm"
197 A 512-bit ZMM SIMD register (zmm0-zmm31).
198
199 "zmm{k}"
200 A 512-bit ZMM SIMD register (zmm0-zmm31), optionally merge-masked by an AVX-512 mask register (k1-k7).
201
202 "zmm{k}{z}"
203 A 512-bit ZMM SIMD register (zmm0-zmm31), optionally masked by an AVX-512 mask register (k1-k7).
204
205 "k"
206 An AVX-512 mask register (k0-k7).
207
208 "k{k}"
209 An AVX-512 mask register (k0-k7), optionally merge-masked by an AVX-512 mask register (k1-k7).
210
211 "m"
212 A memory operand of any size.
213
214 "m8"
215 An 8-bit memory operand.
216
217 "m16"
218 A 16-bit memory operand.
219
220 "m16{k}{z}"
221 A 16-bit memory operand, optionally masked by an AVX-512 mask register (k1-k7).
222
223 "m32"
224 A 32-bit memory operand.
225
226 "m32{k}"
227 A 32-bit memory operand, optionally merge-masked by an AVX-512 mask register (k1-k7).
228
229 "m32{k}{z}"
230 A 32-bit memory operand, optionally masked by an AVX-512 mask register (k1-k7).
231
232 "m64"
233 A 64-bit memory operand.
234
235 "m64{k}"
236 A 64-bit memory operand, optionally merge-masked by an AVX-512 mask register (k1-k7).
237
238 "m64{k}{z}"
239 A 64-bit memory operand, optionally masked by an AVX-512 mask register (k1-k7).
240
241 "m80"
242 An 80-bit memory operand.
243
244 "m128"
245 A 128-bit memory operand.
246
247 "m128{k}{z}"
248 A 128-bit memory operand, optionally masked by an AVX-512 mask register (k1-k7).
249
250 "m256"
251 A 256-bit memory operand.
252
253 "m256{k}{z}"
254 A 256-bit memory operand, optionally masked by an AVX-512 mask register (k1-k7).
255
256 "m512"
257 A 512-bit memory operand.
258
259 "m512{k}{z}"
260 A 512-bit memory operand, optionally masked by an AVX-512 mask register (k1-k7).
261
262 "m64/m32bcst"
263 A 64-bit memory operand or a 32-bit memory operand broadcasted to 64 bits {1to2}.
264
265 "m128/m32bcst"
266 A 128-bit memory operand or a 32-bit memory operand broadcasted to 128 bits {1to4}.
267
268 "m256/m32bcst"
269 A 256-bit memory operand or a 32-bit memory operand broadcasted to 256 bits {1to8}.
270
271 "m512/m32bcst"
272 A 512-bit memory operand or a 32-bit memory operand broadcasted to 512 bits {1to16}.
273
274 "m128/m64bcst"
275 A 128-bit memory operand or a 64-bit memory operand broadcasted to 128 bits {1to2}.
276
277 "m256/m64bcst"
278 A 256-bit memory operand or a 64-bit memory operand broadcasted to 256 bits {1to4}.
279
280 "m512/m64bcst"
281 A 512-bit memory operand or a 64-bit memory operand broadcasted to 512 bits {1to8}.
282
283 "vm32x"
284 A vector of memory addresses using VSIB with 32-bit indices in XMM register.
285
286 "vm32x{k}"
287 A vector of memory addresses using VSIB with 32-bit indices in XMM register merge-masked by an AVX-512 mask
288 register (k1-k7).
289
290 "vm32y"
291 A vector of memory addresses using VSIB with 32-bit indices in YMM register.
292
293 "vm32y{k}"
294 A vector of memory addresses using VSIB with 32-bit indices in YMM register merge-masked by an AVX-512 mask
295 register (k1-k7).
296
297 "vm32z"
298 A vector of memory addresses using VSIB with 32-bit indices in ZMM register.
299
300 "vm32z{k}"
301 A vector of memory addresses using VSIB with 32-bit indices in ZMM register merge-masked by an AVX-512 mask
302 register (k1-k7).
303
304 "vm64x"
305 A vector of memory addresses using VSIB with 64-bit indices in XMM register.
306
307 "vm64x{k}"
308 A vector of memory addresses using VSIB with 64-bit indices in XMM register merge-masked by an AVX-512 mask
309 register (k1-k7).
310
311 "vm64y"
312 A vector of memory addresses using VSIB with 64-bit indices in YMM register.
313
314 "vm64y{k}"
315 A vector of memory addresses using VSIB with 64-bit indices in YMM register merge-masked by an AVX-512 mask
316 register (k1-k7).
317
318 "vm64z"
319 A vector of memory addresses using VSIB with 64-bit indices in ZMM register.
320
321 "vm64z{k}"
322 A vector of memory addresses using VSIB with 64-bit indices in ZMM register merge-masked by an AVX-512 mask
323 register (k1-k7).
324
325 "{sae}"
326 Suppress-all-exceptions modifier. This operand is optional and can be omitted.
327
328 "{er}"
329 Embedded rounding control. This operand is optional and can be omitted.
330
331 :ivar is_input: indicates if the instruction reads the variable specified by this operand.
332 :ivar is_output: indicates if the instruction writes the variable specified by this operand.
333 :ivar extended_size: for immediate operands the size of the value in bytes after size-extension.
334
335 The extended size affects which operand values can be encoded. E.g. a signed imm8 operand would normally \
336 encode values in the [-128, 127] range. But if it is extended to 4 bytes, it can also encode values in \
337 [2**32 - 128, 2**32 - 1] range.
338 """
339 def __init__(self, type):
340 self.type = type
341 self.is_input = False
342 self.is_output = False
343 self.extended_size = None
344
345 def __str__(self):
346 """Return string representation of the operand type and its read/write attributes"""
347 return {
348 (False, False): self.type,
349 (True, False): "[in] " + self.type,
350 (False, True): "[out] " + self.type,
351 (True, True): "[in/out] " + self.type
352 }[(self.is_input, self.is_output)]
353
354 def __repr__(self):
355 return str(self)
356
357 @property
358 def is_variable(self):
359 """Indicates whether this operand refers to a variable (i.e. specifies either a register or a memory location)"""
360 return self.is_input or self.is_output
361
362 @property
363 def is_register(self):
364 """Indicates whether this operand specifies a register"""
365 return self.type.replace("{k}{z}", "").replace("{k}", "") \
366 in ["al", "cl", "ax", "eax", "rax", "xmm0", "r8", "r16", "r32", "r64", "r8l", "r16l", "r32l", "mm", "xmm", "ymm", "zmm", "k"]
367
368 @property
369 def is_memory(self):
370 """Indicates whether this operand specifies a memory location"""
371 return self.type.replace("{k}{z}", "").replace("{k}", "") \
372 in ["m", "m8", "m16", "m32", "m64", "m80", "m128", "m256", "m512",
373 "m64/m32bcst", "m128/m32bcst", "m256/m32bcst", "m512/m32bcst",
374 "m128/m64bcst", "m256/m64bcst", "m512/m64bcst",
375 "vm32x", "vm32y", "vm32z", "vm64x", "vm64y", "vm64z"]
376
377 @property
378 def is_immediate(self):
379 """Indicates whether this operand is an immediate constant"""
380 return self.type in ["imm4", "imm8", "imm16", "imm32", "imm64"]
381
382
383 class ISAExtension:
384 _score_map = {
385 "CPUID": 1,
386 "RDTSC": 5,
387 "RDTSCP": 6,
388 "CMOV": 20,
389 "MOVBE": 99,
390 "POPCNT": 100,
391 "LZCNT": 101,
392 "TBM": 102,
393 "BMI": 103,
394 "BMI2": 104,
395 "ADX": 105,
396 "MMX": 30,
397 "MMX+": 31,
398 "FEMMS": 40,
399 "3dnow!": 41,
400 "3dnow!+": 42,
401 "SSE": 50,
402 "SSE2": 51,
403 "SSE3": 52,
404 "SSSE3": 53,
405 "SSE4A": 54,
406 "SSE4.1": 55,
407 "SSE4.2": 56,
408 "FMA3": 60,
409 "FMA4": 61,
410 "XOP": 62,
411 "F16C": 63,
412 "AVX": 70,
413 "AVX2": 71,
414 "AVX512F": 72,
415 "AVX512BW": 73,
416 "AVX512DQ": 74,
417 "AVX512VL": 75,
418 'AVX512PF': 76,
419 'AVX512ER': 77,
420 'AVX512CD': 78,
421 'AVX512VBMI': 79,
422 'AVX512IFMA': 80,
423 "RDRAND": 85,
424 "RDSEED": 86,
425 "PCLMULQDQ": 90,
426 "AES": 91,
427 "SHA": 92,
428 }
429
430 """An extension to x86-64 instruction set.
431
432 :ivar name: name of the ISA extension. Possible values are:
433
434 - "RDTSC" := The `RDTSC` instruction.
435 - "RDTSCP" := The `RDTSCP` instruction.
436 - "CPUID" := The `CPUID` instruction.
437 - "FEMMS" := The `FEMMS` instruction.
438 - "MOVBE" := The `MOVBE` instruction.
439 - "POPCNT" := The `POPCNT` instruction.
440 - "LZCNT" := The `LZCNT` instruction.
441 - "PCLMULQDQ" := The `PCLMULQDQ` instruction.
442 - "RDRAND" := The `RDRAND` instruction.
443 - "RDSEED" := The `RDSEED` instruction.
444 - "CLFLUSH" := The `CLFLUSH` instruction.
445 - "CLFLUSHOPT" := The `CLFLUSHOPT` instruction.
446 - "CLWB" := The `CLWB` instruction.
447 - "CLZERO" := The `CLZERO` instruction.
448 - "PREFETCH" := The `PREFETCH` instruction (3dnow! Prefetch).
449 - "PREFETCHW" := The `PREFETCHW` instruction (3dnow! Prefetch/Intel PRFCHW).
450 - "PREFETCHWT1" := The `PREFETCHWT1` instruction.
451 - "MONITOR" := The `MONITOR` and `MWAIT` instructions.
452 - "MONITORX" := The `MONITORX` and `MWAITX` instructions.
453 - "CMOV" := Conditional MOVe instructions.
454 - "MMX" := MultiMedia eXtension.
455 - "MMX+" := AMD MMX+ extension / Integer SSE (Intel).
456 - "3dnow!" := AMD 3dnow! extension.
457 - "3dnow+!" := AMD 3dnow!+ extension.
458 - "SSE" := Streaming SIMD Extension.
459 - "SSE2" := Streaming SIMD Extension 2.
460 - "SSE3" := Streaming SIMD Extension 3.
461 - "SSSE3" := Supplemental Streaming SIMD Extension 3.
462 - "SSE4.1" := Streaming SIMD Extension 4.1.
463 - "SSE4.2" := Streaming SIMD Extension 4.2.
464 - "SSE4A" := Streaming SIMD Extension 4a.
465 - "AVX" := Advanced Vector eXtension.
466 - "AVX2" := Advanced Vector eXtension 2.
467 - "AVX512F" := AVX-512 Foundation instructions.
468 - "AVX512BW" := AVX-512 Byte and Word instructions.
469 - "AVX512DQ" := AVX-512 Doubleword and Quadword instructions.
470 - "AVX512VL" := AVX-512 Vector Length extension (EVEX-encoded XMM/YMM operations).
471 - "AVX512PF" := AVX-512 Prefetch instructions.
472 - "AVX512ER" := AVX-512 Exponential and Reciprocal instructions.
473 - "AVX512CD" := AVX-512 Conflict Detection instructions.
474 - "AVX512VBMI" := AVX-512 Vector Bit Manipulation instructions.
475 - "AVX512IFMA" := AVX-512 Integer 52-bit Multiply-Accumulate instructions.
476 - "AVX512VPOPCNTDQ" := AVX-512 Vector Population Count instructions.
477 - "XOP" := eXtended OPerations extension.
478 - "F16C" := Half-Precision (F16) Conversion instructions.
479 - "FMA3" := Fused Multiply-Add instructions (3-operand).
480 - "FMA4" := Fused Multiply-Add instructions (4-operand).
481 - "BMI" := Bit Manipulation Instructions.
482 - "BMI2" := Bit Manipulation Instructions 2.
483 - "TBM" := Trailing Bit Manipulation instructions.
484 - "ADX" := The `ADCX` and `ADOX` instructions.
485 - "AES" := `AES` instruction set.
486 - "SHA" := `SHA` instruction set.
487 """
488
489 def __init__(self, name):
490 self.name = name
491
492 def __str__(self):
493 """Returns the name of the ISA extension"""
494 return self.name
495
496 def __repr__(self):
497 return str(self)
498
499 def __eq__(self, other):
500 return isinstance(other, ISAExtension) and self.name == other.name
501
502 def __ne__(self, other):
503 return not isinstance(other, ISAExtension) or self.name != other.name
504
505 def __hash__(self):
506 return hash(self.name)
507
508 @property
509 def score(self):
510 """A number that can be used to order a list of ISA extensions"""
511 return self._score_map.get(self.name, 0)
512
513
514 class Encoding:
515 """Instruction encoding
516
517 :ivar components: a list of :class:`Prefix`, :class:`REX`, :class:`VEX`, :class:`Opcode`, :class:`ModRM`, \
518 :class:`RegisterByte`, :class:`Immediate`, :class:`DataOffset`, :class:`CodeOffset` objects that \
519 specify the components of encoded instruction
520 """
521
522 def __init__(self):
523 self.components = []
524
525
526 class Prefix:
527 """0x66/0xF2/0xF3 prefix
528
529 :ivar is_mandatory: indicates that the prefix is used not for its primary purpose, but for extending instruction \
530 opcode. Mandatory prefixes are common in SSE instructions. Non-mandatory prefix is usually 0x66 that modifies \
531 the instruction to operate on 16-bit operands.
532 :ivar byte: numerical representation of the prefix byte.
533 """
534
535 def __init__(self):
536 self.byte = None
537 self.is_mandatory = None
538
539
540 class REX:
541 """REX prefix.
542
543 Encoding may have only one REX prefix and if present, it immediately precedes the opcode.
544
545 :ivar is_mandatory: indicates whether the REX prefix must be encoded even if no extended registers are used.
546
547 REX is mandatory for most 64-bit instructions (encoded with REX.W = 1) and instructions that operate on the \
548 extended set of 8-bit registers (to indicate access to dil/sil/bpl/spl as opposed to ah/bh/ch/dh which use the \
549 same ModR/M).
550
551 :ivar W: the REX.W bit. Possible values are 0, 1, and None.
552
553 None indicates that the bit is ignored.
554
555 :ivar R: the REX.R bit. Possible values are 0, 1, None, or a reference to one of the instruction operands.
556
557 The value None indicates that this bit is ignored. \
558 If R is a reference to an instruction operand, the operand is of register type and REX.R bit specifies the \
559 high bit (bit 3) of the register number.
560
561 :ivar B: the REX.B bit. Possible values are 0, 1, None, or a reference to one of the instruction operands.
562
563 The value None indicates that this bit is ignored. \
564 If R is a reference to an instruction operand, the operand can be of register or memory type. If the operand \
565 is of register type, the REX.R bit specifies the high bit (bit 3) of the register number, and the REX.X bit is \
566 ignored. If the operand is of memory type, the REX.R bit specifies the high bit (bit 3) of the base register \
567 number, and the X instance variable refers to the same operand.
568
569 :ivar X: the REX.X bit. Possible values are 0, 1, None, or a reference to one of the instruction operands.
570
571 The value None indicates that this bit is ignored. \
572 If X is a reference to an instruction operand, the operand is of memory type and the REX.X bit specifies the \
573 high bit (bit 3) of the index register number, and the B instance variable refers to the same operand.
574 """
575
576 def __init__(self):
577 self.is_mandatory = None
578 self.W = None
579 self.R = None
580 self.X = None
581 self.B = None
582
583 def set_ignored(self, w=0, r=0, x=0, b=0):
584 """Sets values for ignored bits
585
586 :param int w: the value (0 or 1) to be assigned to REX.W bit if it is ignored.
587 :param int r: the value (0 or 1) to be assigned to REX.R bit if it is ignored.
588 :param int x: the value (0 or 1) to be assigned to REX.X bit if it is ignored.
589 :param int b: the value (0 or 1) to be assigned to REX.B bit if it is ignored.
590 """
591 assert w in [0, 1], "REX.W can be only 0 or 1"
592 assert r in [0, 1], "REX.R can be only 0 or 1"
593 assert x in [0, 1], "REX.X can be only 0 or 1"
594 assert b in [0, 1], "REX.B can be only 0 or 1"
595 if self.W is None:
596 self.W = w
597 if self.R is None:
598 self.R = r
599 if self.X is None:
600 self.X = x
601 if self.B is None:
602 self.B = b
603
604
605 class VEX:
606 """VEX or XOP prefix.
607
608 VEX and XOP prefixes use the same format and differ only by leading byte.
609 The `type` property helps to differentiate between the two prefix types.
610
611 Encoding may have only one VEX prefix and if present, it immediately precedes the opcode, and no other prefix is \
612 allowed.
613
614 :ivar type: the type of the leading byte for VEX encoding. Possible values are:
615
616 "VEX"
617 The VEX prefix (0xC4 or 0xC5) is used.
618
619 "XOP"
620 The XOP prefix (0x8F) is used.
621
622 :ivar mmmmm: the VEX m-mmmm (implied leading opcode bytes) field. In AMD documentation this field is called map_select. Possible values are:
623
624 0b00001
625 Implies 0x0F leading opcode byte.
626
627 0b00010
628 Implies 0x0F 0x38 leading opcode bytes.
629
630 0b00011
631 Implies 0x0F 0x3A leading opcode bytes.
632
633 0b01000
634 This value does not have opcode byte interpretation. Only XOP instructions use this value.
635
636 0b01001
637 This value does not have opcode byte interpretation. Only XOP and TBM instructions use this value.
638
639 0b01010
640 This value does not have opcode byte interpretation. Only TBM instructions use this value.
641
642 Only VEX prefix with m-mmmm equal to 0b00001 could be encoded in two bytes.
643
644 :ivar pp: the VEX pp (implied legacy prefix) field. Possible values are:
645
646 0b00
647 No implied prefix.
648
649 0b01
650 Implied 0x66 prefix.
651
652 0b10
653 Implied 0xF3 prefix.
654
655 0b11
656 Implied 0xF2 prefix.
657
658 :ivar W: the VEX.W bit. Possible values are 0, 1, and None.
659
660 None indicates that the bit is ignored.
661
662 :ivar L: the VEX.L bit. Possible values are 0, 1, and None.
663
664 None indicates that the bit is ignored.
665
666 :ivar R: the VEX.R bit. Possible values are 0, 1, None, or a reference to one of the instruction operands.
667
668 The value None indicates that this bit is ignored. \
669 If R is a reference to an instruction operand, the operand is of register type and VEX.R bit specifies the \
670 high bit (bit 3) of the register number.
671
672 :ivar B: the VEX.B bit. Possible values are 0, 1, None, or a reference to one of the instruction operands.
673
674 The value None indicates that this bit is ignored. \
675 If R is a reference to an instruction operand, the operand can be of register or memory type. If the operand is \
676 of register type, the VEX.R bit specifies the high bit (bit 3) of the register number, and the VEX.X bit is \
677 ignored. If the operand is of memory type, the VEX.R bit specifies the high bit (bit 3) of the base register \
678 number, and the X instance variable refers to the same operand.
679
680 :ivar X: the VEX.X bit. Possible values are 0, 1, None, or a reference to one of the instruction operands.
681
682 The value None indicates that this bit is ignored. \
683 If X is a reference to an instruction operand, the operand is of memory type and the VEX.X bit specifies the \
684 high bit (bit 3) of the index register number, and the B instance variable refers to the same operand.
685
686 :ivar vvvv: the VEX vvvv field. Possible values are 0b0000 or a reference to one of the instruction operands.
687
688 The value 0b0000 indicates that this field is not used. \
689 If vvvv is a reference to an instruction operand, the operand is of register type and VEX.vvvv field specifies \
690 its number.
691 """
692
693 def __init__(self):
694 self.type = None
695 self.mmmmm = None
696 self.pp = None
697 self.W = None
698 self.L = None
699 self.R = None
700 self.X = None
701 self.B = None
702 self.vvvv = None
703
704 def set_ignored(self, w=0, l=0, r=0, x=0, b=0):
705 """Sets values for ignored bits
706
707 :param int w: the value (0 or 1) to be assigned to VEX.W bit if it is ignored.
708 :param int l: the value (0 or 1) to be assigned to VEX.L bit if it is ignored.
709 :param int r: the value (0 or 1) to be assigned to VEX.R bit if it is ignored.
710 :param int x: the value (0 or 1) to be assigned to VEX.X bit if it is ignored.
711 :param int b: the value (0 or 1) to be assigned to VEX.B bit if it is ignored.
712 """
713 assert w in [0, 1], "VEX.W can be only 0 or 1"
714 assert l in [0, 1], "VEX.L can be only 0 or 1"
715 assert r in [0, 1], "VEX.R can be only 0 or 1"
716 assert x in [0, 1], "VEX.X can be only 0 or 1"
717 assert b in [0, 1], "VEX.B can be only 0 or 1"
718 if self.W is None:
719 self.W = w
720 if self.L is None:
721 self.L = l
722 if self.R is None:
723 self.R = r
724 if self.X is None:
725 self.X = x
726 if self.B is None:
727 self.B = b
728
729
730 class EVEX:
731 """EVEX prefix.
732
733 Encoding may have only one EVEX prefix and if present, it immediately precedes the opcode, and no other prefix is \
734 allowed.
735
736 :ivar mm: the EVEX mm (compressed legacy escape) field. Identical to two low bits of VEX.m-mmmm field. Possible \
737 values are:
738
739 0b01
740 Implies 0x0F leading opcode byte.
741
742 0b10
743 Implies 0x0F 0x38 leading opcode bytes.
744
745 0b11
746 Implies 0x0F 0x3A leading opcode bytes.
747
748 :ivar pp: the EVEX pp (compressed legacy prefix) field. Possible values are:
749
750 0b00
751 No implied prefix.
752
753 0b01
754 Implied 0x66 prefix.
755
756 0b10
757 Implied 0xF3 prefix.
758
759 0b11
760 Implied 0xF2 prefix.
761
762 :ivar W: the EVEX.W bit. Possible values are 0, 1, and None.
763
764 None indicates that the bit is ignored.
765
766 :ivar LL: the EVEX.L'L bits. Specify either vector length for the operation, or explicit rounding control \
767 (in which case operation is 512 bits wide). Possible values:
768
769 None
770 Indicates that the EVEX.L'L field is ignored.
771
772 0b00
773 128-bits wide operation.
774
775 0b01
776 256-bits wide operation.
777
778 0b10
779 512-bits wide operation.
780
781 Reference to the last instruction operand
782 EVEX.L'L are interpreted as rounding control and set to the value specified by the operand. If the rounding
783 control operand is omitted, EVEX.L'L is set to 0b10 (embedded rounding control is only supported for 512-bit
784 wide operations).
785
786 :ivar RR: the EVEX.R'R bits. Possible values are None, or a reference to an register-type instruction operand.
787
788 None indicates that the field is ignored.
789 The R' bit specifies bit 4 of the register number and the R bit specifies bit 3 of the register number.
790
791 :ivar B: the EVEX.B bit. Possible values are None, or a reference to one of the instruction operands.
792
793 None indicates that this bit is ignored. \
794 If R is a reference to an instruction operand, the operand can be of register or memory type. If the operand is\
795 of register type, the EVEX.R bit specifies the high bit (bit 3) of the register number, and the EVEX.X bit is \
796 ignored. If the operand is of memory type, the EVEX.R bit specifies the high bit (bit 3) of the base register \
797 number, and the X instance variable refers to the same operand.
798
799 :ivar X: the EVEX.X bit. Possible values are None, or a reference to one of the instruction operands.
800
801 The value None indicates that this bit is ignored. \
802 If X is a reference to an instruction operand, the operand is of memory type and the EVEX.X bit specifies the \
803 high bit (bit 3) of the index register number, and the B instance variable refers to the same operand.
804
805 :ivar vvvv: the EVEX vvvv field. Possible values are 0b0000 or a reference to one of the instruction operands.
806
807 The value 0b0000 indicates that this field is not used. \
808 If vvvv is a reference to an instruction operand, the operand is of register type and EVEX.vvvv field \
809 specifies the register number.
810
811 :ivar V: the EVEX V field. Possible values are 0, or a reference to one of the instruction operands.
812
813 The value 0 indicates that this field is not used (EVEX.vvvv is not used or encodes a general-purpose register).
814
815 :ivar b: the EVEX b (broadcast/rounding control/suppress all exceptions context) bit. Possible values are 0 or a \
816 reference to one of the instruction operands.
817
818 The value 0 indicates that this field is not used. \
819 If b is a reference to an instruction operand, the operand can be a memory operand with optional broadcasting, \
820 an optional rounding specification, or an optional Suppress-all-exceptions specification. \
821 If b is a reference to a memory operand, EVEX.b encodes whether broadcasting is used to the operand. \
822 If b is a reference to a optional rounding control specification, EVEX.b encodes whether explicit rounding \
823 control is used. \
824 If b is a reference to a suppress-all-exceptions specification, EVEX.b encodes whether suppress-all-exceptions \
825 is enabled.
826
827 :ivar aaa: the EVEX aaa (embedded opmask register specifier) field. Possible values are 0 or a reference to one of \
828 the instruction operands.
829
830 The value 0 indicates that this field is not used. \
831 If aaa is a reference to an instruction operand, the operand supports register mask, and EVEX.aaa encodes the \
832 mask register.
833
834 :ivar z: the EVEX z bit. Possible values are None, 0 or a reference to one of the instruction operands.
835
836 None indicates that the bit is ignored. \
837 The value 0 indicates that the bit is not used. \
838 If z is a reference to an instruction operand, the operand supports zero-masking with register mask, and \
839 EVEX.z indicates whether zero-masking is used.
840
841 :ivar disp8xN: the N value used for encoding compressed 8-bit displacement. Possible values are powers of 2 in \
842 [1, 64] range or None.
843
844 None indicates that this instruction form does not use displacement (the form has no memory operands).
845 """
846
847 def __init__(self):
848 self.mm = None
849 self.pp = None
850 self.W = None
851 self.LL = None
852 self.RR = None
853 self.B = None
854 self.X = None
855 self.vvvv = None
856 self.V = None
857 self.b = None
858 self.aaa = None
859 self.z = None
860 self.disp8xN = None
861
862 def set_ignored(self, w=0, ll=0, rr=0, x=0, z=0):
863 """Sets values for ignored bits
864
865 :param int w: the value (0 or 1) to be assigned to EVEX.W bit if it is ignored.
866 :param int ll: the value (0b00, 0b01, 0b10, or 0b11) to be assigned to EVEX.L'L field if it is ignored.
867 :param int rr: the value (0b00, 0b01, 0b10, or 0b11) to be assigned to EVEX.R'R field if it is ignored.
868 :param int x: the value (0 or 1) to be assigned to EVEX.X bit if it is ignored.
869 :param int z: the value (0 or 1) to be assigned to EVEX.z bit if it is ignored.
870 """
871 assert w in [0, 1], "EVEX.W can be only 0 or 1"
872 assert ll in [0b00, 0b01, 0b10, 0b11], "EVEX.LL must be a 2-bit integer value"
873 assert rr in [0b00, 0b01, 0b10, 0b11], "EVEX.R'R must be a 2-bit integer value"
874 assert x in [0, 1], "EVEX.X can be only 0 or 1"
875 assert z in [0, 1], "EVEX.z can be only 0 or 1"
876 if self.W is None:
877 self.W = w
878 if self.LL is None:
879 self.LL = ll
880 if self.RR is None:
881 self.RR = rr
882 if self.X is None:
883 self.X = x
884 if self.z is None:
885 self.z = z
886
887
888 class Opcode:
889 """Operation code
890
891 Encoding may include more than one opcode. Opcodes do not necessarily go in sequence.
892
893 :ivar byte: operation code as a byte integer (0 <= `byte` <= 255)
894 :ivar addend: None or a reference to an instruction operand.
895
896 If addend is a reference to an instruction operand, the operand is of register type and the three lowest bits
897 of its number must be ORed with `byte` to produce the final opcode value.
898 """
899 def __init__(self, byte):
900 self.byte = byte
901 self.addend = None
902
903 def __str__(self):
904 return "0x%02X".format(self.byte)
905
906 def __repr__(self):
907 return str(self)
908
909
910 class ModRM:
911 """Mod R/M byte that can encode a register operand, a memory operand, or provide an opcode extension.
912
913 If memory operand requires SIB byte, the SIB byte immediately follows the Mod R/M byte in instruction encoding.
914
915 :ivar mode: addressing mode. Possible values are 0b11 or a reference to an instruction operand.
916
917 If mode value is 0b11, the Mod R/M encodes two register operands or a register operand and an opcode extension.
918
919 If mode is a reference to an instruction operand, the operand has memory type and its addressing mode must be \
920 coded instruction the Mod R/M mode field.
921
922 :ivar rm: a register or memory operand. Must be a reference to an instruction operand.
923
924 If rm is a reference to a operand, rm specifies bits 0-2 of the register number. If the operand is of memory \
925 type, rm specifies bits 0-2 of the base register number unless a SIB byte is used.
926
927 :ivar reg: a register or an opcode extension. Possible values are an int value, or a reference to an instruction \
928 operand.
929
930 If reg is an int value, this value extends the opcode and must be directly coded in the reg field.
931
932 If reg is a reference to an instruction operand, the operand is of register type, and the reg field specifies \
933 bits 0-2 of the register number.
934 """
935 def __init__(self):
936 self.mode = None
937 self.rm = None
938 self.reg = None
939
940 def set_ignored(self, mode=0b11, rm=0):
941 """Sets values for ignored fields
942
943 :param int mode: the value (0b00, 0b01, 0b10, or 0b11) to be assigned to Mod R/M mode field if it is ignored.
944 :param int rm: the value (an integer, 0 <= rm <= 7) to be assigned to Mod R/M rm field if it is ignored.
945 """
946 assert mode in [0b00, 0b01, 0b10, 0b11], "Mod R/M mode must be 0b00, 0b01, 0b10 or 0b11"
947 assert rm in [0, 1, 2, 3, 4, 5, 6, 7], "Mod R/M rm must be an integer in 0-7 range"
948 if self.mode is None:
949 self.mode = mode
950 if self.rm is None:
951 self.rm = rm
952
953
954 class Immediate:
955 """Immediate constant embedded into instruction encoding.
956
957 :ivar size: size of the constant in bytes. Possible values are 1, 2, 4, or 8.
958 :ivar value: value of the constant. Can be an int value or a reference to an instruction operand.
959
960 If value is a reference to an instruction operand, the operand has "imm" type of the matching size.
961 """
962 def __init__(self):
963 self.size = None
964 self.value = None
965
966
967 class RegisterByte:
968 """Byte that encodes a register in the low 4 bits and optionally encodes an immediate value in the high 4 bits.
969
970 :ivar register: a reference to an instruction operand of register type. The register number is encoded in the low \
971 4 bits of the byte (register number is in 0..15 for all instructions which use this encoding component).
972
973 :ivar payload: value of the high 4 bits of the byte. Can be None or a reference to an instruction operand of imm4 \
974 type.
975
976 None indicates that this high 4 bits are not used. \
977 The only instructions that use the payload are VPERMIL2PD and VPERMIL2PS from XOP instruction set.
978 """
979 def __init__(self):
980 self.register = None
981 self.payload = None
982
983
984 class CodeOffset:
985 """Relative code offset embedded into instruction encoding.
986
987 Offset is relative to the end of the instruction.
988
989 :ivar size: size of the offset in bytes. Possible values are 1 or 4.
990 :ivar value: value of the offset. Must be a reference to an instruction operand.
991
992 The instruction operand has "rel" type of the matching size.
993 """
994 def __init__(self):
995 self.size = None
996 self.value = None
997
998
999 class DataOffset:
1000 """Absolute data offset embedded into instruction encoding.
1001
1002 Only MOV instruction has forms that use direct data offset.
1003
1004 :ivar size: size of the offset in bytes. Possible values are 4 or 8.
1005 :ivar value: value of the offset. Must be a reference to an instruction operand.
1006
1007 The instruction operand has "moffs" type of the matching size.
1008 """
1009 def __init__(self):
1010 self.size = None
1011 self.value = None
1012
1013
1014 def _parse_boolean(xml_boolean):
1015 """Converts strings "true" and "false" from XML files to Python bool"""
1016
1017 if xml_boolean is not None:
1018 assert xml_boolean in ["true", "false"], \
1019 "The boolean string must be \"true\" or \"false\""
1020 return {"true": True, "false": False}[xml_boolean]
1021
1022
1023 def _parse_value(value, operands, base=None):
1024 """Parses string, which can be a number, a reference to an operand, or None
1025
1026 :param value: the string to parse.
1027 :param operands: the list of operands. If value starts with "#", it is interpreted as a reference to an operand.
1028 :param base: the base of the integer representation of value.
1029 """
1030 if value is not None:
1031 if value.startswith("#"):
1032 return operands[int(value[1:])]
1033 else:
1034 assert base is not None
1035 return int(value, base)
1036
1037
1038 def read_instruction_set(filename=None):
1039 """Reads instruction set data from an XML file and returns a list of :class:`Instruction` objects
1040
1041 :param filename: path to an XML file with instruction set data
1042 """
1043 if filename is None:
•1044 data = (files("opcodes").joinpath("x86_64.xml")).open('rb')
1045 xml_tree = ET.parse(data)
1046 else:
1047 xml_tree = ET.parse(filename)
1048
1049 xml_instruction_set = xml_tree.getroot()
1050 assert xml_instruction_set.tag == "InstructionSet"
1051 assert xml_instruction_set.attrib["name"] == "x86-64"
1052
1053 instruction_set = []
1054 for xml_instruction in xml_instruction_set:
1055 assert xml_instruction.tag == "Instruction"
1056 instruction = Instruction(xml_instruction.attrib["name"])
1057 instruction.summary = xml_instruction.attrib["summary"]
1058 for xml_instruction_form in xml_instruction:
1059 instruction_form = InstructionForm(instruction.name)
1060 instruction_form.gas_name = xml_instruction_form.attrib["gas-name"]
1061 instruction_form.go_name = xml_instruction_form.attrib.get("go-name")
1062 instruction_form.mmx_mode = xml_instruction_form.attrib.get("mmx-mode")
1063 instruction_form.xmm_mode = xml_instruction_form.attrib.get("xmm-mode")
1064 instruction_form.cancelling_inputs = \
1065 _parse_boolean(xml_instruction_form.attrib.get("cancelling-inputs", "false"))
1066 instruction_form.nacl_version = _parse_value(xml_instruction_form.attrib.get("nacl-version"), [], 10)
1067 instruction_form.nacl_zero_extends_outputs = \
1068 _parse_boolean(xml_instruction_form.attrib.get("nacl-zero-extends-outputs"))
1069 for xml_operand in xml_instruction_form.findall("Operand"):
1070 operand = Operand(xml_operand.attrib["type"])
1071 operand.is_input = _parse_boolean(xml_operand.attrib.get("input", "false"))
1072 operand.is_output = _parse_boolean(xml_operand.attrib.get("output", "false"))
1073 operand.extended_size = _parse_value(xml_operand.attrib.get("extended-size"), [], 10)
1074 instruction_form.operands.append(operand)
1075 for xml_implicit_operand in xml_instruction_form.findall("ImplicitOperand"):
1076 if _parse_boolean(xml_implicit_operand.attrib["input"]):
1077 instruction_form.implicit_inputs.add(xml_implicit_operand.attrib["id"])
1078 if _parse_boolean(xml_implicit_operand.attrib["output"]):
1079 instruction_form.implicit_outputs.add(xml_implicit_operand.attrib["id"])
1080 for xml_isa_extension in xml_instruction_form.findall("ISA"):
1081 isa_extension = ISAExtension(xml_isa_extension.attrib["id"])
1082 instruction_form.isa_extensions.append(isa_extension)
1083 for xml_encoding in xml_instruction_form.findall("Encoding"):
1084 encoding = Encoding()
1085 for xml_component in xml_encoding:
1086 if xml_component.tag == "Prefix":
1087 prefix = Prefix()
1088 prefix.byte = _parse_value(xml_component.attrib.get("byte"), [], 16)
1089 assert prefix.byte in [0x66, 0xF2, 0xF3]
1090 prefix.is_mandatory = _parse_boolean(xml_component.attrib.get("mandatory"))
1091 encoding.components.append(prefix)
1092 elif xml_component.tag == "REX":
1093 rex = REX()
1094 rex.is_mandatory = _parse_boolean(xml_component.attrib["mandatory"])
1095 rex.W = _parse_value(xml_component.attrib.get("W"), [], 2)
1096 rex.R = _parse_value(xml_component.attrib.get("R"), instruction_form.operands, 2)
1097 rex.B = _parse_value(xml_component.attrib.get("B"), instruction_form.operands, 2)
1098 rex.X = _parse_value(xml_component.attrib.get("X"), instruction_form.operands, 2)
1099 encoding.components.append(rex)
1100 elif xml_component.tag == "VEX":
1101 vex = VEX()
1102 vex.type = xml_component.attrib["type"]
1103 vex.pp = int(xml_component.attrib["pp"], 2)
1104 vex.mmmmm = int(xml_component.attrib["m-mmmm"], 2)
1105 vex.W = _parse_value(xml_component.attrib.get("W"), [], 2)
1106 vex.L = _parse_value(xml_component.attrib.get("L"), [], 2)
1107 vex.R = _parse_value(xml_component.attrib.get("R"), instruction_form.operands, 2)
1108 vex.B = _parse_value(xml_component.attrib.get("B"), instruction_form.operands, 2)
1109 vex.X = _parse_value(xml_component.attrib.get("X"), instruction_form.operands)
1110 vex.vvvv = _parse_value(xml_component.attrib.get("vvvv"), instruction_form.operands, 2)
1111 encoding.components.append(vex)
1112 elif xml_component.tag == "EVEX":
1113 evex = EVEX()
1114 evex.pp = int(xml_component.attrib["pp"], 2)
1115 evex.mm = int(xml_component.attrib["mm"], 2)
1116 evex.W = _parse_value(xml_component.attrib.get("W"), [], 2)
1117 evex.LL = _parse_value(xml_component.attrib.get("LL"), instruction_form.operands, 2)
1118 evex.vvvv = _parse_value(xml_component.attrib["vvvv"], instruction_form.operands, 2)
1119 evex.V = _parse_value(xml_component.attrib["V"], instruction_form.operands, 2)
1120 evex.aaa = _parse_value(xml_component.attrib["aaa"], instruction_form.operands, 2)
1121 evex.z = _parse_value(xml_component.attrib["z"], instruction_form.operands, 2)
1122 evex.X = _parse_value(xml_component.attrib.get("X"), instruction_form.operands)
1123 evex.B = _parse_value(xml_component.attrib["B"], instruction_form.operands)
1124 evex.RR = _parse_value(xml_component.attrib.get("RR"), instruction_form.operands)
1125 evex.b = _parse_value(xml_component.attrib["b"], instruction_form.operands, 2)
1126 evex.disp8xN = _parse_value(xml_component.attrib.get("disp8xN"), [], 10)
1127 encoding.components.append(evex)
1128 elif xml_component.tag == "Opcode":
1129 opcode = Opcode(int(xml_component.attrib["byte"], 16))
1130 opcode.addend = _parse_value(xml_component.get("addend"), instruction_form.operands)
1131 encoding.components.append(opcode)
1132 elif xml_component.tag == "ModRM":
1133 modrm = ModRM()
1134 modrm.mode = _parse_value(xml_component.attrib.get("mode"), instruction_form.operands, 2)
1135 modrm.reg = _parse_value(xml_component.attrib.get("reg"), instruction_form.operands, 10)
1136 modrm.rm = _parse_value(xml_component.attrib.get("rm"), instruction_form.operands)
1137 encoding.components.append(modrm)
1138 elif xml_component.tag == "Immediate":
1139 assert "size" in xml_component.attrib
1140 immediate = Immediate()
1141 immediate.size = int(xml_component.attrib["size"])
1142 assert immediate.size in [1, 2, 4, 8]
1143 immediate.value = _parse_value(xml_component.attrib.get("value"), instruction_form.operands)
1144 encoding.components.append(immediate)
1145 elif xml_component.tag == "RegisterByte":
1146 register_byte = RegisterByte()
1147 register_byte.register = _parse_value(xml_component.attrib.get("register"), instruction_form.operands)
1148 register_byte.payload = _parse_value(xml_component.attrib.get("payload"), instruction_form.operands)
1149 encoding.components.append(register_byte)
1150 elif xml_component.tag == "CodeOffset":
1151 assert "size" in xml_component.attrib
1152 code_offset = CodeOffset()
1153 code_offset.size = int(xml_component.attrib["size"])
1154 assert code_offset.size in [1, 4]
1155 code_offset.value = _parse_value(xml_component.attrib.get("value"), instruction_form.operands)
1156 encoding.components.append(code_offset)
1157 elif xml_component.tag == "DataOffset":
1158 assert "size" in xml_component.attrib
1159 data_offset = DataOffset()
1160 data_offset.size = int(xml_component.attrib["size"])
1161 assert data_offset.size in [4, 8]
1162 data_offset.value = _parse_value(xml_component.attrib.get("value"), instruction_form.operands)
1163 encoding.components.append(data_offset)
1164 else:
1165 print("Unknown encoding tag: " + xml_component.tag)
1166
1167 instruction_form.encodings.append(encoding)
1168 instruction.forms.append(instruction_form)
1169 instruction_set.append(instruction)
1170 return instruction_set