Debian Codegraph @

opcodes/x86.py

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