Module disassembler

CIL instruction decoding and disassembly based on ECMA-335.

This module provides comprehensive CIL (Common Intermediate Language) instruction decoding and disassembly capabilities. It implements the complete ECMA-335 instruction set with support for control flow analysis and stack effect tracking.

Architecture

The disassembler is built around several core concepts:

• Instruction Decoding: Binary CIL bytecode to structured instruction representation
• Control Flow Analysis: Building basic blocks and analyzing program flow
• Stack Effect Analysis: Tracking how instructions affect the evaluation stack
• Exception Handling: Parsing try/catch/finally regions and exception handlers

Key Components

• crate::disassembler::Instruction - Represents a decoded CIL instruction
• crate::disassembler::BasicBlock - A sequence of instructions with single entry/exit
• crate::disassembler::Operand - Instruction operands (immediates, tokens, targets)
• crate::disassembler::FlowType - How instructions affect control flow
• crate::disassembler::decode_instruction - Decode a single instruction
• crate::disassembler::decode_stream - Decode a sequence of instructions
• crate::disassembler::decode_blocks - Build basic blocks from instruction stream

Usage Examples

use dotscope::{disassembler::decode_instruction, Parser};

let bytecode = &[0x00, 0x2A]; // nop, ret
let mut parser = Parser::new(bytecode);
let instruction = decode_instruction(&mut parser, 0x1000)?;

println!("Mnemonic: {}", instruction.mnemonic);
println!("Flow type: {:?}", instruction.flow_type);

Integration

The disassembler integrates with the metadata system to resolve tokens and provide rich semantic information about method calls, field access, and type operations.

Thread Safety

All disassembler types are Send and Sync for safe concurrent processing. CIL (Common Intermediate Language) disassembler and instruction decoding engine.

This module provides comprehensive support for decoding, analyzing, and disassembling CIL bytecode from .NET assemblies according to ECMA-335 specifications. It implements a complete disassembly pipeline including instruction parsing, control flow analysis, stack effect tracking, and basic block construction for advanced static analysis capabilities.

Architecture

The disassembler is organized into several cooperating components: instruction decoding transforms raw bytecode into structured instruction objects, control flow analysis builds basic blocks with predecessor/successor relationships, and metadata integration provides semantic context for method-level analysis.

Key Components

• crate::disassembler::Instruction - Complete decoded CIL instruction representation
• crate::disassembler::BasicBlock - Control flow basic block with instruction sequences
• crate::disassembler::Operand - Type-safe instruction operand representation
• crate::disassembler::FlowType - Control flow behavior classification
• crate::disassembler::decode_instruction - Core single instruction decoder
• crate::disassembler::decode_stream - Linear instruction sequence decoder
• crate::disassembler::decode_blocks - Complete control flow analysis with basic blocks

Usage Examples

use dotscope::disassembler::{decode_instruction, decode_stream, decode_blocks};
use dotscope::Parser;

// Decode a single instruction
let bytecode = &[0x2A]; // ret
let mut parser = Parser::new(bytecode);
let instruction = decode_instruction(&mut parser, 0x1000)?;
println!("Instruction: {}", instruction.mnemonic);

// Decode a sequence of instructions
let bytecode = &[0x00, 0x2A]; // nop, ret
let mut parser = Parser::new(bytecode);
let instructions = decode_stream(&mut parser, 0x1000)?;
assert_eq!(instructions.len(), 2);

// Decode with control flow analysis
let bytecode = &[0x00, 0x2A]; // nop, ret
let blocks = decode_blocks(bytecode, 0, 0x1000, None)?;
assert_eq!(blocks.len(), 1);

Integration

This module integrates with:

• crate::metadata::method - Provides method-level disassembly and caching
• crate::metadata::token - Resolves metadata token references in operands

Structs

BasicBlock

Represents a basic block in the control flow graph.

CilInstruction

Metadata for a CIL instruction definition.

Instruction

A decoded CIL instruction with all metadata needed for analysis and emulation.

StackBehavior

Stack effect of an instruction.

Enums

FlowType

How an instruction affects control flow.

Immediate

Represents an immediate value type embedded in CIL instructions.

InstructionCategory

Categorization of instructions by their primary function.

Operand

Represents an operand in a more structured way.

OperandType

Types of operands for CIL instructions.

Constants

INSTRUCTIONS

Lookup table for single-byte CIL instruction metadata.

INSTRUCTIONS_FE

Lookup table for double-byte CIL instruction metadata (0xFE prefix).

INSTRUCTIONS_FE_MAX

Maximum opcode value for double-byte CIL instructions prefixed with 0xFE.

INSTRUCTIONS_MAX

Maximum opcode value for single-byte CIL instructions.

Functions

decode_blocks

Decodes bytecode into a collection of basic blocks with control flow analysis.

decode_instruction

Decodes a single CIL instruction from the current parser position.

decode_stream

Decodes a continuous stream of CIL instructions from a byte stream.