Rooba
/
iced
mirror of https://github.com/icedland/iced.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Split up example code into smaller how-tos

This commit is contained in:
0xd4d 2020-01-24 18:00:21 +01:00
parent 3cb30c17d8
commit 4d577ea27e
2 changed files with 455 additions and 396 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

837
README.md
View File

@ -7,8 +7,8 @@ High performance x86 (16/32/64-bit) instruction decoder, disassembler and assemb
It can be used for static analysis of x86/x64 binaries, to rewrite code (eg. remove garbage instructions), to relocate code or as a disassembler. It can be used for static analysis of x86/x64 binaries, to rewrite code (eg. remove garbage instructions), to relocate code or as a disassembler.
- Supports all Intel and AMD instructions - Supports all Intel and AMD instructions
- High level [Assembler](#Assembler) providing a simple and lean syntax (e.g `asm.mov(eax, edx)`)) - High level [Assembler](#assemble-instructions) providing a simple and lean syntax (e.g `asm.mov(eax, edx)`))
- [Decoding](#Decoding) and disassembler support: - [Decoding](#disassemble-decode-and-format-instructions) and disassembler support:
- The decoder doesn't allocate any memory and is 2x-5x+ faster than other similar libraries written in C or C# - The decoder doesn't allocate any memory and is 2x-5x+ faster than other similar libraries written in C or C#
- Small decoded instructions, only 32 bytes - Small decoded instructions, only 32 bytes
- The formatter supports masm, nasm, gas (AT&T), Intel (XED) and there are many options to customize the output - The formatter supports masm, nasm, gas (AT&T), Intel (XED) and there are many options to customize the output
@ -17,7 +17,8 @@ It can be used for static analysis of x86/x64 binaries, to rewrite code (eg. rem
- The block encoder encodes a list of instructions and optimizes branches to short, near or 'long' (64-bit: 1 or more instructions) - The block encoder encodes a list of instructions and optimizes branches to short, near or 'long' (64-bit: 1 or more instructions)
- API to get instruction info, eg. read/written registers, memory and rflags bits; CPUID feature flag, flow control info, etc - API to get instruction info, eg. read/written registers, memory and rflags bits; CPUID feature flag, flow control info, etc
- All instructions are tested (decode, encode, format, instruction info) - All instructions are tested (decode, encode, format, instruction info)
- Supports of `.NET Standard 2.0/2.1+` and `.NET Framework 4.5+` - Supports `.NET Standard 2.0/2.1+` and `.NET Framework 4.5+`
- License: MIT
# Classes # Classes
@ -28,8 +29,8 @@ Decoder:
- `Decoder` - `Decoder`
- `Instruction` (and `Instruction.Create()` methods) - `Instruction` (and `Instruction.Create()` methods)
- `CodeReader` - `CodeReader`
- `ByteArrayCodeReader` - `ByteArrayCodeReader`
- `StreamCodeReader` - `StreamCodeReader`
- `InstructionList` - `InstructionList`
- `ConstantOffsets` - `ConstantOffsets`
- `IcedFeatures.Initialize()` - `IcedFeatures.Initialize()`
@ -37,20 +38,26 @@ Decoder:
Formatters: Formatters:
- `Formatter` - `Formatter`
- `MasmFormatter` - `MasmFormatter`
- `NasmFormatter` - `NasmFormatter`
- `GasFormatter` - `GasFormatter`
- `IntelFormatter` - `IntelFormatter`
- `FormatterOptions` - `FormatterOptions`
- `MasmFormatterOptions` - `MasmFormatterOptions`
- `NasmFormatterOptions` - `NasmFormatterOptions`
- `GasFormatterOptions` - `GasFormatterOptions`
- `IntelFormatterOptions` - `IntelFormatterOptions`
- `FormatterOutput` - `FormatterOutput`
- `StringOutput` - `StringOutput`
- `ISymbolResolver` - `ISymbolResolver`
- `IFormatterOptionsProvider` - `IFormatterOptionsProvider`
Assembler:
- `Assembler`
- `Label`
- `AssemblerRegisters` (use `using static` to have access directly to registers e.g `eax`, `rdi`, `xmm1`...)
Encoder: Encoder:
- `Encoder` - `Encoder`
@ -68,46 +75,24 @@ Instruction info:
- `MemorySizeExtensions` - `MemorySizeExtensions`
- `RegisterExtensions` - `RegisterExtensions`
High Level Assembler: # How-tos
- `Assembler` - [Disassemble (decode and format instructions)](#disassemble-decode-and-format-instructions)
- `Label` - [Assemble instructions](#assemble-instructions)
- `AssemblerRegisters` (use `using static` to have access directly to registers e.g `eax`, `rdi`, `xmm1`...) - [Disassemble with a symbol resolver](#disassemble-with-a-symbol-resolver)
- [Disassemble with colorized text](#disassemble-with-colorized-text)
- [Move code in memory (eg. hook a function)](#move-code-in-memory-eg-hook-a-function)
- [Get instruction info, eg. read/written regs/mem, control flow info, etc](#get-instruction-info-eg-readwritten-regsmem-control-flow-info-etc)
# Examples ## Disassemble (decode and format instructions)
## Decoding
For another example, see [JitDasm](https://github.com/0xd4d/JitDasm).
```C# ```C#
using System; using System;
using System.Collections.Generic;
using Iced.Intel; using Iced.Intel;
namespace Iced.Examples { static class HowTo_Disassemble {
static class Program { /*
const int HEXBYTES_COLUMN_BYTE_LENGTH = 10; * This method produces the following output:
static void Main(string[] args) {
IcedFeatures.Initialize();
DecoderFormatterExample();
EncoderExample();
CreateInstructionsExample();
InstructionInfoExample();
}
const int exampleCodeBitness = 64;
const ulong exampleCodeRIP = 0x00007FFAC46ACDA4;
static readonly byte[] exampleCode = new byte[] {
0x48, 0x89, 0x5C, 0x24, 0x10, 0x48, 0x89, 0x74, 0x24, 0x18, 0x55, 0x57, 0x41, 0x56, 0x48, 0x8D,
0xAC, 0x24, 0x00, 0xFF, 0xFF, 0xFF, 0x48, 0x81, 0xEC, 0x00, 0x02, 0x00, 0x00, 0x48, 0x8B, 0x05,
0x18, 0x57, 0x0A, 0x00, 0x48, 0x33, 0xC4, 0x48, 0x89, 0x85, 0xF0, 0x00, 0x00, 0x00, 0x4C, 0x8B,
0x05, 0x2F, 0x24, 0x0A, 0x00, 0x48, 0x8D, 0x05, 0x78, 0x7C, 0x04, 0x00, 0x33, 0xFF
};
/*
* This method produces the following output:
00007FFAC46ACDA4 48895C2410 mov [rsp+10h],rbx 00007FFAC46ACDA4 48895C2410 mov [rsp+10h],rbx
00007FFAC46ACDA9 4889742418 mov [rsp+18h],rsi 00007FFAC46ACDA9 4889742418 mov [rsp+18h],rsi
00007FFAC46ACDAE 55 push rbp 00007FFAC46ACDAE 55 push rbp
@ -121,217 +106,358 @@ namespace Iced.Examples {
00007FFAC46ACDD2 4C8B052F240A00 mov r8,[rel 7FFA`C474`F208h] 00007FFAC46ACDD2 4C8B052F240A00 mov r8,[rel 7FFA`C474`F208h]
00007FFAC46ACDD9 488D05787C0400 lea rax,[rel 7FFA`C46F`4A58h] 00007FFAC46ACDD9 488D05787C0400 lea rax,[rel 7FFA`C46F`4A58h]
00007FFAC46ACDE0 33FF xor edi,edi 00007FFAC46ACDE0 33FF xor edi,edi
*/ */
static void DecoderFormatterExample() { public static void Example() {
// You can also pass in a hex string, eg. "90 91 929394", or you can use your own CodeReader // You can also pass in a hex string, eg. "90 91 929394", or you can use your own CodeReader
// reading data from a file or memory etc // reading data from a file or memory etc
var codeBytes = exampleCode; var codeBytes = exampleCode;
var codeReader = new ByteArrayCodeReader(codeBytes); var codeReader = new ByteArrayCodeReader(codeBytes);
var decoder = Decoder.Create(exampleCodeBitness, codeReader); var decoder = Decoder.Create(exampleCodeBitness, codeReader);
decoder.IP = exampleCodeRIP; decoder.IP = exampleCodeRIP;
ulong endRip = decoder.IP + (uint)codeBytes.Length; ulong endRip = decoder.IP + (uint)codeBytes.Length;
// This list is faster than List<Instruction> since it uses refs to the Instructions // This list is faster than List<Instruction> since it uses refs to the Instructions
// instead of copying them (each Instruction is 32 bytes in size). It has a ref indexer, // instead of copying them (each Instruction is 32 bytes in size). It has a ref indexer,
// and a ref iterator. Add() uses 'in' (ref readonly). // and a ref iterator. Add() uses 'in' (ref readonly).
var instructions = new InstructionList(); var instructions = new InstructionList();
while (decoder.IP < endRip) { while (decoder.IP < endRip) {
// The method allocates an uninitialized element at the end of the list and // The method allocates an uninitialized element at the end of the list and
// returns a reference to it which is initialized by Decode(). // returns a reference to it which is initialized by Decode().
decoder.Decode(out instructions.AllocUninitializedElement()); decoder.Decode(out instructions.AllocUninitializedElement());
}
// Formatters: Masm*, Nasm*, Gas* (AT&T) and Intel* (XED)
var formatter = new NasmFormatter();
formatter.Options.DigitSeparator = "`";
formatter.Options.FirstOperandCharIndex = 10;
var output = new StringOutput();
// Use InstructionList's ref iterator (C# 7.3) to prevent copying 32 bytes every iteration
foreach (ref var instr in instructions) {
// Don't use instr.ToString(), it allocates more, uses masm syntax and default options
formatter.Format(instr, output);
Console.Write(instr.IP.ToString("X16"));
Console.Write(" ");
int instrLen = instr.Length;
int byteBaseIndex = (int)(instr.IP - exampleCodeRIP);
for (int i = 0; i < instrLen; i++)
Console.Write(codeBytes[byteBaseIndex + i].ToString("X2"));
int missingBytes = HEXBYTES_COLUMN_BYTE_LENGTH - instrLen;
for (int i = 0; i < missingBytes; i++)
Console.Write(" ");
Console.Write(" ");
Console.WriteLine(output.ToStringAndReset());
}
} }
/* // Formatters: Masm*, Nasm*, Gas* (AT&T) and Intel* (XED)
* This method produces the following output: var formatter = new NasmFormatter();
New code bytes: formatter.Options.DigitSeparator = "`";
0x48, 0x89, 0x5C, 0x24, 0x10, 0x48, 0x89, 0x74, 0x24, 0x18, 0x55, 0x57, 0x41, 0x56, 0x48, 0x8D formatter.Options.FirstOperandCharIndex = 10;
0xAC, 0x24, 0x00, 0xFF, 0xFF, 0xFF, 0x48, 0x81, 0xEC, 0x00, 0x02, 0x00, 0x00, 0x48, 0x8B, 0x05 var output = new StringOutput();
0x18, 0x57, 0xEA, 0xFF, 0x48, 0x33, 0xC4, 0x48, 0x89, 0x85, 0xF0, 0x00, 0x00, 0x00, 0x4C, 0x8B // Use InstructionList's ref iterator (C# 7.3) to prevent copying 32 bytes every iteration
0x05, 0x2F, 0x24, 0xEA, 0xFF, 0x48, 0x8D, 0x05, 0x78, 0x7C, 0xE4, 0xFF, 0x33, 0xFF foreach (ref var instr in instructions) {
Disassembled code: // Don't use instr.ToString(), it allocates more, uses masm syntax and default options
00007FFAC48ACDA4 mov [rsp+10h],rbx formatter.Format(instr, output);
00007FFAC48ACDA9 mov [rsp+18h],rsi Console.Write(instr.IP.ToString("X16"));
00007FFAC48ACDAE push rbp Console.Write(" ");
00007FFAC48ACDAF push rdi int instrLen = instr.Length;
00007FFAC48ACDB0 push r14 int byteBaseIndex = (int)(instr.IP - exampleCodeRIP);
00007FFAC48ACDB2 lea rbp,[rsp-100h] for (int i = 0; i < instrLen; i++)
00007FFAC48ACDBA sub rsp,200h Console.Write(codeBytes[byteBaseIndex + i].ToString("X2"));
00007FFAC48ACDC1 mov rax,[rel 7FFA`C475`24E0h] int missingBytes = HEXBYTES_COLUMN_BYTE_LENGTH - instrLen;
00007FFAC48ACDC8 xor rax,rsp for (int i = 0; i < missingBytes; i++)
00007FFAC48ACDCB mov [rbp+0F0h],rax Console.Write(" ");
00007FFAC48ACDD2 mov r8,[rel 7FFA`C474`F208h] Console.Write(" ");
00007FFAC48ACDD9 lea rax,[rel 7FFA`C46F`4A58h] Console.WriteLine(output.ToStringAndReset());
00007FFAC48ACDE0 xor edi,edi
*/
static void EncoderExample() {
var codeReader = new ByteArrayCodeReader(exampleCode);
var decoder = Decoder.Create(exampleCodeBitness, codeReader);
decoder.IP = exampleCodeRIP;
ulong endRip = decoder.IP + (uint)exampleCode.Length;
var instructions = new InstructionList();
while (decoder.IP < endRip)
decoder.Decode(out instructions.AllocUninitializedElement());
// Relocate the code to some new location. It can fix short/near branches and
// convert them to short/near/long forms if needed. This also works even if it's a
// jrcxz/loop/loopcc instruction which only has a short form.
//
// It can currently only fix RIP relative operands if the new location is within 2GB
// of the target data location.
//
// There's also a simpler Encoder class which is used by BlockEncoder, but it can only
// encode one instruction at a time and doesn't fix branches.
//
// Note that a block is not the same thing as a basic block. A block can contain any
// number of instructions, including any number of branch instructions. One block
// should be enough unless you must relocate different blocks to different locations.
var codeWriter = new CodeWriterImpl();
ulong relocatedBaseAddress = exampleCodeRIP + 0x200000;
var block = new InstructionBlock(codeWriter, instructions, relocatedBaseAddress);
// This method can also encode more than one block but that's rarely needed, see above comment.
bool success = BlockEncoder.TryEncode(decoder.Bitness, block, out var errorMessage, out _);
if (!success) {
Console.WriteLine($"ERROR: {errorMessage}");
return;
}
var newCode = codeWriter.ToArray();
Console.WriteLine("New code bytes:");
for (int i = 0; i < newCode.Length;) {
for (int j = 0; j < 16 && i < newCode.Length; i++, j++) {
if (j != 0)
Console.Write(", ");
Console.Write("0x");
Console.Write(newCode[i].ToString("X2"));
}
Console.WriteLine();
}
// Disassemble the new relocated code. It's identical to the original code except that
// the RIP relative instructions have been updated.
Console.WriteLine("Disassembled code:");
var formatter = new NasmFormatter();
formatter.Options.DigitSeparator = "`";
formatter.Options.FirstOperandCharIndex = 10;
var output = new StringOutput();
var newDecoder = Decoder.Create(decoder.Bitness, new ByteArrayCodeReader(newCode));
newDecoder.IP = block.RIP;
endRip = newDecoder.IP + (uint)newCode.Length;
while (newDecoder.IP < endRip) {
newDecoder.Decode(out var instr);
formatter.Format(instr, output);
Console.WriteLine($"{instr.IP:X16} {output.ToStringAndReset()}");
}
} }
// Simple and inefficient code writer that stores the data in a List<byte>, with a ToArray() method }
// to get the data
sealed class CodeWriterImpl : CodeWriter { const int HEXBYTES_COLUMN_BYTE_LENGTH = 10;
readonly List<byte> allBytes = new List<byte>(); const int exampleCodeBitness = 64;
public override void WriteByte(byte value) => allBytes.Add(value); const ulong exampleCodeRIP = 0x00007FFAC46ACDA4;
public byte[] ToArray() => allBytes.ToArray(); static readonly byte[] exampleCode = new byte[] {
0x48, 0x89, 0x5C, 0x24, 0x10, 0x48, 0x89, 0x74, 0x24, 0x18, 0x55, 0x57, 0x41, 0x56, 0x48, 0x8D,
0xAC, 0x24, 0x00, 0xFF, 0xFF, 0xFF, 0x48, 0x81, 0xEC, 0x00, 0x02, 0x00, 0x00, 0x48, 0x8B, 0x05,
0x18, 0x57, 0x0A, 0x00, 0x48, 0x33, 0xC4, 0x48, 0x89, 0x85, 0xF0, 0x00, 0x00, 0x00, 0x4C, 0x8B,
0x05, 0x2F, 0x24, 0x0A, 0x00, 0x48, 0x8D, 0x05, 0x78, 0x7C, 0x04, 0x00, 0x33, 0xFF
};
}
```
## Assemble instructions
```C#
using System;
using System.IO;
using Iced.Intel;
using static Iced.Intel.AssemblerRegisters;
static class HowTo_Assemble {
/*
* This method produces the following output:
10000000 = push r15
10000002 = add rax,r15
10000005 = mov rax,[rax]
10000008 = mov rax,[rax]
1000000B = cmp dword ptr [rax+rcx*8+10h],0FFFFFFFFh
10000010 = jne short 0000000010000031h
10000012 = inc rax
10000015 = lea rcx,[10000031h]
1000001C = rep stosd
1000001E = xacquire lock add qword ptr [rax+rcx],7Bh
10000025 = vaddpd zmm1{k3}{z},zmm2,zmm3 {rz-sae}
1000002B = vunpcklps xmm2{k5}{z},xmm6,dword bcst [rax]
10000031 = pop r15
10000033 = ret
*/
public static MemoryStream Example() {
// The assembler supports all modes: 16-bit, 32-bit and 64-bit.
var c = Assembler.Create(64);
var label1 = c.CreateLabel();
c.push(r15);
c.add(rax, r15);
// If the memory operand can only have one size, __[] can be used. The assembler ignores
// the memory size unless it's an ambiguous instruction, eg. 'add [mem],123'
c.mov(rax, __[rax]);
c.mov(rax, __qword_ptr[rax]);
// The assembler must know the memory size to pick the correct instruction
c.cmp(__dword_ptr[rax + rcx * 8 + 0x10], -1);
c.jne(label1); // Jump to Label1
c.inc(rax);
// Labels can be referenced by memory operands (64-bit only) and call/jmp/jcc/loopcc instructions
c.lea(rcx, __[label1]);
// The assembler has prefix properties that will be added to the following instruction
c.rep.stosd();
c.xacquire.@lock.add(__qword_ptr[rax + rcx], 123);
// The assembler defaults to VEX instructions. If you need EVEX instructions, set PreferVex=false
c.PreferVex = false;
// AVX-512 decorators are properties on the memory and register operands
c.vaddpd(zmm1.k3.z, zmm2, zmm3.rz_sae);
// To broadcast memory, use the __dword_bcst/__qword_bcst memory types
c.vunpcklps(xmm2.k5.z, xmm6, __dword_bcst[rax]);
// Emit label1:
c.Label(ref label1);
c.pop(r15);
c.ret();
const ulong RIP = 0x1000_0000;
var stream = new MemoryStream();
c.Assemble(new StreamCodeWriter(stream), RIP);
// Disassemble the result
stream.Position = 0;
var reader = new StreamCodeReader(stream);
var decoder = Decoder.Create(64, reader);
decoder.IP = RIP;
while (stream.Position < stream.Length) {
decoder.Decode(out var instr);
Console.WriteLine($"{instr.IP:X} = {instr}");
} }
/* return stream;
* This method produces the following output: }
Disassembled code: }
00007FFAC48ACDA4 push rbp ```
00007FFAC48ACDA5 push rdi
00007FFAC48ACDA6 push rsi
00007FFAC48ACDA7 sub rsp,50h
00007FFAC48ACDAE vzeroupper
00007FFAC48ACDB1 lea rbp,[rsp+60h]
00007FFAC48ACDB6 mov rsi,rcx
00007FFAC48ACDB9 lea rdi,[rbp-38h]
00007FFAC48ACDBD mov ecx,0Ah
00007FFAC48ACDC2 xor eax,eax
00007FFAC48ACDC4 rep stosd
00007FFAC48ACDC6 mov rcx,rsi
00007FFAC48ACDC9 mov [rbp+10h],rcx
00007FFAC48ACDCD mov [rbp+18h],rdx
*/
static void CreateInstructionsExample() {
const int bitness = 64;
var instructions = new InstructionList(); ## Disassemble with a symbol resolver
// push rbp
instructions.Add(Instruction.Create(Code.Push_r64, Register.RBP));
// push rdi
instructions.Add(Instruction.Create(Code.Push_r64, Register.RDI));
// push rsi
instructions.Add(Instruction.Create(Code.Push_r64, Register.RSI));
// sub rsp,50h
instructions.Add(Instruction.Create(Code.Sub_rm64_imm32, Register.RSP, 0x50));
// vzeroupper
instructions.Add(Instruction.Create(Code.VEX_Vzeroupper));
// lea rbp,[rsp+60h]
instructions.Add(Instruction.Create(Code.Lea_r64_m, Register.RBP, new MemoryOperand(Register.RSP, 0x60)));
// mov rsi,rcx
instructions.Add(Instruction.Create(Code.Mov_r64_rm64, Register.RSI, Register.RCX));
// lea rdi,[rbp-38h]
instructions.Add(Instruction.Create(Code.Lea_r64_m, Register.RDI, new MemoryOperand(Register.RBP, -0x38)));
// mov ecx,0Ah
instructions.Add(Instruction.Create(Code.Mov_r32_imm32, Register.ECX, 0x0A));
// xor eax,eax
instructions.Add(Instruction.Create(Code.Xor_r32_rm32, Register.EAX, Register.EAX));
// rep stosd
instructions.Add(Instruction.CreateStosd(bitness, RepPrefixKind.Repe));
// mov rcx,rsi
instructions.Add(Instruction.Create(Code.Mov_r64_rm64, Register.RCX, Register.RSI));
// mov [rbp+10h],rcx
instructions.Add(Instruction.Create(Code.Mov_rm64_r64, new MemoryOperand(Register.RBP, 0x10), Register.RCX));
// mov [rbp+18h],rdx
instructions.Add(Instruction.Create(Code.Mov_rm64_r64, new MemoryOperand(Register.RBP, 0x18), Register.RDX));
var codeWriter = new CodeWriterImpl(); ```C#
ulong relocatedBaseAddress = exampleCodeRIP + 0x200000; using System;
var block = new InstructionBlock(codeWriter, instructions, relocatedBaseAddress); using System.Collections.Generic;
bool success = BlockEncoder.TryEncode(bitness, block, out var errorMessage, out _); using Iced.Intel;
if (!success) {
Console.WriteLine($"ERROR: {errorMessage}");
return;
}
var newCode = codeWriter.ToArray(); static class HowTo_SymbolResolver {
Console.WriteLine("Disassembled code:"); sealed class SymbolResolver : ISymbolResolver {
var formatter = new NasmFormatter(); readonly Dictionary<ulong, string> symbolDict;
formatter.Options.DigitSeparator = "`";
formatter.Options.FirstOperandCharIndex = 10; public SymbolResolver(Dictionary<ulong, string> symbolDict) {
var output = new StringOutput(); this.symbolDict = symbolDict;
var newDecoder = Decoder.Create(bitness, new ByteArrayCodeReader(newCode));
newDecoder.IP = block.RIP;
ulong endRip = newDecoder.IP + (uint)newCode.Length;
while (newDecoder.IP < endRip) {
newDecoder.Decode(out var instr);
formatter.Format(instr, output);
Console.WriteLine($"{instr.IP:X16} {output.ToStringAndReset()}");
}
} }
/* public bool TryGetSymbol(in Instruction instruction, int operand, int instructionOperand,
* This method produces the following output: ulong address, int addressSize, out SymbolResult symbol) {
if (symbolDict.TryGetValue(address, out var symbolText)) {
// The 'address' arg is the address of the symbol and doesn't have to be identical
// to the 'address' arg passed to TryGetSymbol(). If it's different from the input
// address, the formatter will add +N or -N, eg. '[rax+symbol+123]'
symbol = new SymbolResult(address, symbolText);
return true;
}
symbol = default;
return false;
}
}
public static void Example() {
var symbols = new Dictionary<ulong, string> {
{ 0x5AA55AA5UL, "my_data" },
};
var symbolResolver = new SymbolResolver(symbols);
var decoder = Decoder.Create(64, new ByteArrayCodeReader("488B8AA55AA55A"));
decoder.Decode(out var instr);
var formatter = new GasFormatter(null, symbolResolver);
var output = new StringOutput();
formatter.Format(instr, output);
// Prints: mov my_data(%rdx),%rcx
Console.WriteLine(output.ToStringAndReset());
}
}
```
## Disassemble with colorized text
```C#
using System;
using System.Collections.Generic;
using Iced.Intel;
static class HowTo_ColorizedText {
public static void Example() {
var codeReader = new ByteArrayCodeReader(exampleCode);
var decoder = Decoder.Create(exampleCodeBitness, codeReader);
decoder.IP = exampleCodeRIP;
var formatter = new MasmFormatter();
var output = new FormatterOutputImpl();
while (codeReader.CanReadByte) {
decoder.Decode(out var instr);
output.List.Clear();
formatter.Format(instr, output);
foreach (var (text, kind) in output.List) {
Console.ForegroundColor = GetColor(kind);
Console.Write(text);
}
Console.WriteLine();
}
Console.ResetColor();
}
sealed class FormatterOutputImpl : FormatterOutput {
public List<(string text, FormatterTextKind kind)> List =
new List<(string text, FormatterTextKind kind)>();
public override void Write(string text, FormatterTextKind kind) => List.Add((text, kind));
}
static ConsoleColor GetColor(FormatterTextKind kind) {
switch (kind) {
case FormatterTextKind.Directive:
case FormatterTextKind.Keyword:
return ConsoleColor.Yellow;
case FormatterTextKind.Prefix:
case FormatterTextKind.Mnemonic:
return ConsoleColor.Red;
case FormatterTextKind.Register:
return ConsoleColor.Magenta;
case FormatterTextKind.Number:
return ConsoleColor.Green;
default:
return ConsoleColor.White;
}
}
const int exampleCodeBitness = 64;
const ulong exampleCodeRIP = 0x00007FFAC46ACDA4;
static readonly byte[] exampleCode = new byte[] {
0x48, 0x89, 0x5C, 0x24, 0x10, 0x48, 0x89, 0x74, 0x24, 0x18, 0x55, 0x57, 0x41, 0x56, 0x48, 0x8D,
0xAC, 0x24, 0x00, 0xFF, 0xFF, 0xFF, 0x48, 0x81, 0xEC, 0x00, 0x02, 0x00, 0x00, 0x48, 0x8B, 0x05,
0x18, 0x57, 0x0A, 0x00, 0x48, 0x33, 0xC4, 0x48, 0x89, 0x85, 0xF0, 0x00, 0x00, 0x00, 0x4C, 0x8B,
0x05, 0x2F, 0x24, 0x0A, 0x00, 0x48, 0x8D, 0x05, 0x78, 0x7C, 0x04, 0x00, 0x33, 0xFF
};
}
```
## Move code in memory (eg. hook a function)
```C#
using System;
using System.Collections.Generic;
using Iced.Intel;
static class HowTo_MoveCode {
// Decodes instructions from some address, then encodes them starting at some
// other address. This can be used to hook a function. You decode enough instructions
// until you have enough bytes to add a JMP instruction that jumps to your code.
// Your code will then conditionally jump to the original code that you re-encoded.
//
// This code uses the BlockEncoder which will help with some things, eg. converting
// short branches to longer branches if the target is too far away.
//
// 64-bit mode also supports RIP relative addressing, but the encoder can't rewrite
// those to use a longer displacement. If any of the moved instructions have RIP
// relative addressing and it tries to access data too far away, the encoder will fail.
// The easiest solution is to use OS alloc functions that allocate memory close to the
// original code (+/-2GB).
public static void Example() {
var codeReader = new ByteArrayCodeReader(exampleCode);
var decoder = Decoder.Create(exampleCodeBitness, codeReader);
decoder.IP = exampleCodeRIP;
var instructions = new InstructionList();
while (codeReader.CanReadByte)
decoder.Decode(out instructions.AllocUninitializedElement());
// Relocate the code to some new location. It can fix short/near branches and
// convert them to short/near/long forms if needed. This also works even if it's a
// jrcxz/loop/loopcc instruction which only has a short form.
//
// It can currently only fix RIP relative operands if the new location is within 2GB
// of the target data location.
//
// Note that a block is not the same thing as a basic block. A block can contain any
// number of instructions, including any number of branch instructions. One block
// should be enough unless you must relocate different blocks to different locations.
var codeWriter = new CodeWriterImpl();
ulong relocatedBaseAddress = exampleCodeRIP + 0x200000;
var block = new InstructionBlock(codeWriter, instructions, relocatedBaseAddress);
// This method can also encode more than one block but that's rarely needed, see above comment.
bool success = BlockEncoder.TryEncode(decoder.Bitness, block, out var errorMessage, out _);
if (!success) {
Console.WriteLine($"ERROR: {errorMessage}");
return;
}
var newCode = codeWriter.ToArray();
Console.WriteLine("New code bytes:");
for (int i = 0; i < newCode.Length;) {
for (int j = 0; j < 16 && i < newCode.Length; i++, j++) {
if (j != 0)
Console.Write(", ");
Console.Write("0x");
Console.Write(newCode[i].ToString("X2"));
}
Console.WriteLine();
}
// Disassemble the new relocated code. It's identical to the original code except that
// the RIP relative instructions have been updated.
Console.WriteLine("Disassembled code:");
var formatter = new NasmFormatter();
var output = new StringOutput();
var newReader = new ByteArrayCodeReader(newCode);
var newDecoder = Decoder.Create(decoder.Bitness, newReader);
newDecoder.IP = block.RIP;
while (newReader.CanReadByte) {
newDecoder.Decode(out var instr);
formatter.Format(instr, output);
Console.WriteLine($"{instr.IP:X16} {output.ToStringAndReset()}");
}
}
sealed class CodeWriterImpl : CodeWriter {
readonly List<byte> allBytes = new List<byte>();
public override void WriteByte(byte value) => allBytes.Add(value);
public byte[] ToArray() => allBytes.ToArray();
}
const int exampleCodeBitness = 64;
const ulong exampleCodeRIP = 0x00007FFAC46ACDA4;
static readonly byte[] exampleCode = new byte[] {
0x48, 0x89, 0x5C, 0x24, 0x10, 0x48, 0x89, 0x74, 0x24, 0x18, 0x55, 0x57, 0x41, 0x56, 0x48, 0x8D,
0xAC, 0x24, 0x00, 0xFF, 0xFF, 0xFF, 0x48, 0x81, 0xEC, 0x00, 0x02, 0x00, 0x00, 0x48, 0x8B, 0x05,
0x18, 0x57, 0x0A, 0x00, 0x48, 0x33, 0xC4, 0x48, 0x89, 0x85, 0xF0, 0x00, 0x00, 0x00, 0x4C, 0x8B,
0x05, 0x2F, 0x24, 0x0A, 0x00, 0x48, 0x8D, 0x05, 0x78, 0x7C, 0x04, 0x00, 0x33, 0xFF
};
}
```
## Get instruction info, eg. read/written regs/mem, control flow info, etc
```C#
using System;
using Iced.Intel;
static class HowTo_InstructionInfo {
/*
* This method produces the following output:
00007FFAC46ACDA4 mov [rsp+10h],rbx 00007FFAC46ACDA4 mov [rsp+10h],rbx
OpCode: REX.W 89 /r OpCode: REX.W 89 /r
Instruction: MOV r/m64, r64 Instruction: MOV r/m64, r64
@ -537,159 +663,88 @@ Disassembled code:
Op0: r32_reg Op0: r32_reg
Op1: r32_or_mem Op1: r32_or_mem
RDI:Write RDI:Write
*/ */
static void InstructionInfoExample() { public static void Example() {
var codeReader = new ByteArrayCodeReader(exampleCode); var codeReader = new ByteArrayCodeReader(exampleCode);
var decoder = Decoder.Create(exampleCodeBitness, codeReader); var decoder = Decoder.Create(exampleCodeBitness, codeReader);
decoder.IP = exampleCodeRIP; decoder.IP = exampleCodeRIP;
ulong endRip = decoder.IP + (uint)exampleCode.Length;
// Use a factory to create the instruction info if you need register and // Use a factory to create the instruction info if you need register and
// memory usage. If it's something else, eg. encoding, flags, etc, there // memory usage. If it's something else, eg. encoding, flags, etc, there
// are properties on Instruction that can be used instead. // are properties on Instruction that can be used instead.
var instrInfoFactory = new InstructionInfoFactory(); var instrInfoFactory = new InstructionInfoFactory();
while (decoder.IP < endRip) { while (codeReader.CanReadByte) {
decoder.Decode(out var instr); decoder.Decode(out var instr);
// Gets offsets in the instruction of the displacement and immediates and their sizes. // Gets offsets in the instruction of the displacement and immediates and their sizes.
// This can be useful if there are relocations in the binary. The encoder has a similar // This can be useful if there are relocations in the binary. The encoder has a similar
// method. This method must be called after Decode() and you must pass in the last // method. This method must be called after Decode() and you must pass in the last
// instruction Decode() returned. // instruction Decode() returned.
var offsets = decoder.GetConstantOffsets(instr); var offsets = decoder.GetConstantOffsets(instr);
// A formatter is recommended since this ToString() method defaults to masm syntax, Console.WriteLine($"{instr.IP:X16} {instr}");
// uses default options, and allocates every single time it's called.
var disasmStr = instr.ToString();
Console.WriteLine($"{instr.IP:X16} {disasmStr}");
var opCode = instr.OpCode; var opCode = instr.OpCode;
var info = instrInfoFactory.GetInfo(instr); var info = instrInfoFactory.GetInfo(instr);
const string tab = " "; const string tab = " ";
Console.WriteLine($"{tab}OpCode: {opCode.ToOpCodeString()}"); Console.WriteLine($"{tab}OpCode: {opCode.ToOpCodeString()}");
Console.WriteLine($"{tab}Instruction: {opCode.ToInstructionString()}"); Console.WriteLine($"{tab}Instruction: {opCode.ToInstructionString()}");
Console.WriteLine($"{tab}Encoding: {instr.Encoding}"); Console.WriteLine($"{tab}Encoding: {instr.Encoding}");
Console.WriteLine($"{tab}Mnemonic: {instr.Mnemonic}"); Console.WriteLine($"{tab}Mnemonic: {instr.Mnemonic}");
Console.WriteLine($"{tab}Code: {instr.Code}"); Console.WriteLine($"{tab}Code: {instr.Code}");
Console.WriteLine($"{tab}CpuidFeature: {string.Join(" and ", instr.CpuidFeatures)}"); Console.WriteLine($"{tab}CpuidFeature: {string.Join(" and ", instr.CpuidFeatures)}");
Console.WriteLine($"{tab}FlowControl: {instr.FlowControl}"); Console.WriteLine($"{tab}FlowControl: {instr.FlowControl}");
if (offsets.HasDisplacement) if (offsets.HasDisplacement)
Console.WriteLine($"{tab}Displacement offset = {offsets.DisplacementOffset}, size = {offsets.DisplacementSize}"); Console.WriteLine($"{tab}Displacement offset = {offsets.DisplacementOffset}, size = {offsets.DisplacementSize}");
if (offsets.HasImmediate) if (offsets.HasImmediate)
Console.WriteLine($"{tab}Immediate offset = {offsets.ImmediateOffset}, size = {offsets.ImmediateSize}"); Console.WriteLine($"{tab}Immediate offset = {offsets.ImmediateOffset}, size = {offsets.ImmediateSize}");
if (offsets.HasImmediate2) if (offsets.HasImmediate2)
Console.WriteLine($"{tab}Immediate #2 offset = {offsets.ImmediateOffset2}, size = {offsets.ImmediateSize2}"); Console.WriteLine($"{tab}Immediate #2 offset = {offsets.ImmediateOffset2}, size = {offsets.ImmediateSize2}");
if (instr.IsStackInstruction) if (instr.IsStackInstruction)
Console.WriteLine($"{tab}SP Increment: {instr.StackPointerIncrement}"); Console.WriteLine($"{tab}SP Increment: {instr.StackPointerIncrement}");
if (instr.ConditionCode != ConditionCode.None) if (instr.ConditionCode != ConditionCode.None)
Console.WriteLine($"{tab}Condition code: {instr.ConditionCode}"); Console.WriteLine($"{tab}Condition code: {instr.ConditionCode}");
if (instr.RflagsRead != RflagsBits.None) if (instr.RflagsRead != RflagsBits.None)
Console.WriteLine($"{tab}RFLAGS Read: {instr.RflagsRead}"); Console.WriteLine($"{tab}RFLAGS Read: {instr.RflagsRead}");
if (instr.RflagsWritten != RflagsBits.None) if (instr.RflagsWritten != RflagsBits.None)
Console.WriteLine($"{tab}RFLAGS Written: {instr.RflagsWritten}"); Console.WriteLine($"{tab}RFLAGS Written: {instr.RflagsWritten}");
if (instr.RflagsCleared != RflagsBits.None) if (instr.RflagsCleared != RflagsBits.None)
Console.WriteLine($"{tab}RFLAGS Cleared: {instr.RflagsCleared}"); Console.WriteLine($"{tab}RFLAGS Cleared: {instr.RflagsCleared}");
if (instr.RflagsSet != RflagsBits.None) if (instr.RflagsSet != RflagsBits.None)
Console.WriteLine($"{tab}RFLAGS Set: {instr.RflagsSet}"); Console.WriteLine($"{tab}RFLAGS Set: {instr.RflagsSet}");
if (instr.RflagsUndefined != RflagsBits.None) if (instr.RflagsUndefined != RflagsBits.None)
Console.WriteLine($"{tab}RFLAGS Undefined: {instr.RflagsUndefined}"); Console.WriteLine($"{tab}RFLAGS Undefined: {instr.RflagsUndefined}");
if (instr.RflagsModified != RflagsBits.None) if (instr.RflagsModified != RflagsBits.None)
Console.WriteLine($"{tab}RFLAGS Modified: {instr.RflagsModified}"); Console.WriteLine($"{tab}RFLAGS Modified: {instr.RflagsModified}");
for (int i = 0; i < instr.OpCount; i++) { for (int i = 0; i < instr.OpCount; i++) {
var opKind = instr.GetOpKind(i); var opKind = instr.GetOpKind(i);
if (opKind == OpKind.Memory || opKind == OpKind.Memory64) { if (opKind == OpKind.Memory || opKind == OpKind.Memory64) {
int size = instr.MemorySize.GetSize(); int size = instr.MemorySize.GetSize();
if (size != 0) if (size != 0)
Console.WriteLine($"{tab}Memory size: {size}"); Console.WriteLine($"{tab}Memory size: {size}");
break; break;
}
} }
for (int i = 0; i < instr.OpCount; i++)
Console.WriteLine($"{tab}Op{i}Access: {info.GetOpAccess(i)}");
for (int i = 0; i < opCode.OpCount; i++)
Console.WriteLine($"{tab}Op{i}: {opCode.GetOpKind(i)}");
// The returned iterator is a struct, nothing is allocated unless you box it
foreach (var regInfo in info.GetUsedRegisters())
Console.WriteLine($"{tab}{regInfo.ToString()}");
foreach (var memInfo in info.GetUsedMemory())
Console.WriteLine($"{tab}{memInfo.ToString()}");
} }
for (int i = 0; i < instr.OpCount; i++)
Console.WriteLine($"{tab}Op{i}Access: {info.GetOpAccess(i)}");
for (int i = 0; i < opCode.OpCount; i++)
Console.WriteLine($"{tab}Op{i}: {opCode.GetOpKind(i)}");
// The returned iterator is a struct, nothing is allocated unless you box it
foreach (var regInfo in info.GetUsedRegisters())
Console.WriteLine($"{tab}{regInfo.ToString()}");
foreach (var memInfo in info.GetUsedMemory())
Console.WriteLine($"{tab}{memInfo.ToString()}");
} }
} }
}
```
## Assembler const int exampleCodeBitness = 64;
const ulong exampleCodeRIP = 0x00007FFAC46ACDA4;
Iced provide a high level assembler by providing a friendly syntax close to what a regular assembler could provide: static readonly byte[] exampleCode = new byte[] {
0x48, 0x89, 0x5C, 0x24, 0x10, 0x48, 0x89, 0x74, 0x24, 0x18, 0x55, 0x57, 0x41, 0x56, 0x48, 0x8D,
```c# 0xAC, 0x24, 0x00, 0xFF, 0xFF, 0xFF, 0x48, 0x81, 0xEC, 0x00, 0x02, 0x00, 0x00, 0x48, 0x8B, 0x05,
using Iced.Intel; 0x18, 0x57, 0x0A, 0x00, 0x48, 0x33, 0xC4, 0x48, 0x89, 0x85, 0xF0, 0x00, 0x00, 0x00, 0x4C, 0x8B,
// The following using static allows to import assembler registers 0x05, 0x2F, 0x24, 0x0A, 0x00, 0x48, 0x8D, 0x05, 0x78, 0x7C, 0x04, 0x00, 0x33, 0xFF
// e.g `eax` directly accessible as variables };
using static Iced.Intel.AssemblerRegisters;
public static class AssemblerPlay
{
public static MemoryStream GenerateCode()
{
var c = Assembler.Create(64);
c.push(r15);
c.mov(r15, rsi);
c.mov(rax, __[rdi]);
c.add(rax, r15);
c.pop(r15);
c.ret();
var stream = new MemoryStream();
var writer = new StreamCodeWriter(stream)
c.Encode(writer);
return stream;
}
}
```
The assembler supports the entire instruction set available through the `Encoder` class.
- For prefixes (e.g `rep`, `xacquire`) they are directly accessible on the `Assembler`. For example: `c.rep.movsd()`.
- AVX512+ k1z/sae/rounding flags can be set directly on registers: `c.vaddpd(zmm1.k3.z, zmm2, zmm3.rz_sae)`
- AVX512+ broadcasting can be specified via e.g `__dword_bcst`: `c.vunpcklps(xmm2.k5.z, xmm6, __dword_bcst[rax])`
Labels can be created via `Assembler.CreateLabel`, placed just before an instruction via `Assembler.Label` and referenced by branch instructions:
```c#
using Iced.Intel;
// The following using static allows to import assembler registers
// e.g `eax` directly accessible as variables
using static Iced.Intel.AssemblerRegisters;
public static class AssemblerPlay
{
public static MemoryStream GenerateCode()
{
var c = Assembler.Create(64);
// Create a label
var label1 = c.CreateLabel();
c.push(r15);
c.add(rax, r15);
c.jne(label1); // Jump to Label1
c.inc(rax);
// Emit label1:
c.Label(ref label1);
c.pop(r15);
c.ret();
var stream = new MemoryStream();
var writer = new StreamCodeWriter(stream)
c.Encode(writer);
return stream;
}
} }
``` ```

14
src/csharp/Intel/Iced/Iced.csproj
View File

@ -25,13 +25,17 @@ High performance x86 (16/32/64-bit) instruction decoder, disassembler and assemb
It can be used for static analysis of x86/x64 binaries, to rewrite code (eg. remove garbage instructions), to relocate code or as a disassembler. It can be used for static analysis of x86/x64 binaries, to rewrite code (eg. remove garbage instructions), to relocate code or as a disassembler.
- Supports all Intel and AMD instructions - Supports all Intel and AMD instructions
- The decoder doesn't allocate any memory and is 2x-5x+ faster than other similar libraries written in C or C# - High level Assembler providing a simple and lean syntax (e.g `asm.mov(eax, edx)`))
- Small decoded instructions, only 32 bytes - Decoding and disassembler support:
- The formatter supports masm, nasm, gas (AT&amp;T), Intel (XED) and there are many options to customize the output - The decoder doesn't allocate any memory and is 2x-5x+ faster than other similar libraries written in C or C#
- The encoder can be used to re-encode decoded instructions at any address - Small decoded instructions, only 32 bytes
- The block encoder encodes a list of instructions and optimizes branches to short, near or 'long' (64-bit: 1 or more instructions) - The formatter supports masm, nasm, gas (AT&amp;T), Intel (XED) and there are many options to customize the output
- Encoding support:
- The encoder can be used to re-encode decoded instructions at any address
- The block encoder encodes a list of instructions and optimizes branches to short, near or 'long' (64-bit: 1 or more instructions)
- API to get instruction info, eg. read/written registers, memory and rflags bits; CPUID feature flag, flow control info, etc - API to get instruction info, eg. read/written registers, memory and rflags bits; CPUID feature flag, flow control info, etc
- All instructions are tested (decode, encode, format, instruction info) - All instructions are tested (decode, encode, format, instruction info)
- Supports `.NET Standard 2.0/2.1+` and `.NET Framework 4.5+`
License: MIT License: MIT
</PackageDescription> </PackageDescription>