metasm 1.0.0

data/doc/const_missing.txt

@@ -0,0 +1,16 @@
+The const_missing trick
+=======================
+
+Metasm uses a ruby trick to load most of the framework on demand, so that
+*e.g.* the `MIPS`-related classes are never loaded in the ruby interpreter
+unless you use them.
+
+It is setup by the top-level `metasm.rb` file, by using the ruby mechanism of
+`Module.autoload`. This mechanism will automatically load the specified metasm
+components whenever a reference is made to one of the constants listed here.
+
+Metasm provides a replacement top-level file, `misc/metasm-all.rb`,
+which will unconditionally load all metasm files.
+This will not however load mutually exclusive files, like the Gui subsystems ;
+in this case it will load only the autodetected gui module (win32 or gtk).
+

data/doc/core_classes.txt

@@ -0,0 +1,75 @@
+Core classes
+============
+
+Core
+----
+
+* <core/Expression.txt>
+* <core/EncodedData.txt>
+* <core/VirtualString.txt>
+* <core/Opcode.txt>
+* <core/Instruction.txt>
+
+CPUs
+----
+
+* <core/CPU.txt>
+* <core/Ia32.txt>
+* <core/X86_64.txt>
+* <core/MIPS.txt>
+* <core/PowerPC.txt>
+* <core/Sh4.txt>
+
+ExeFormats
+----------
+
+* <core/ExeFormat.txt>
+* <core/SerialStruct.txt>
+* <core/AutoExe.txt>
+
+* <core/Shellcode.txt>
+* <core/PE.txt>
+* <core/COFF.txt>
+* <core/ELF.txt>
+
+C
+----
+
+* <core/Preprocessor.txt>
+* <core/CParser.txt>
+* <core/CCompiler.txt>
+
+Debugger
+--------
+
+* <core/OS.txt>
+* <core/Debugger.txt>
+* <core/LinDebugger.txt>
+* <core/WinDebugger.txt>
+* <core/PTrace.txt>
+* <core/GdbClient.txt>
+* <core/WinDbgAPI.txt>
+
+Disassembler
+------------
+
+* <core/Disassembler.txt>
+* <core/DecodedFunction.txt>
+* <core/DecodedInstruction.txt>
+* <core/InstructionBlock.txt>
+* <core/Decompiler.txt>
+
+GUI
+----
+
+* <core/Gui.txt>
+* <core/Gui_Drawable.txt>
+* <core/Gui_Window.txt>
+
+* <core/Gui_DasmWidget.txt>
+* <core/Gui_DebugWidget.txt>
+
+Others
+------
+
+* <core/DynLdr.txt>

data/doc/feature_list.txt

@@ -0,0 +1,53 @@
+Metasm feature list
+===================
+
+Metasm is a cross-architecture assembler, disassembler, compiler, linker and debugger.
+
+See <use_cases.txt>
+
+Architectures
+-------------
+
+It is written in such a way that it is easy to add support for new architectures.
+For now, the following architectures are in:
+
+* Intel <core/Ia32.txt> (16 and 32bits)
+* Intel <core/X86_64.txt> (*aka* Ia32 64bits, X64, AMD64)
+* MIPS
+* PowerPC
+* Sh4
+
+The developpement is generally more focused on Ia32 and X86_64.
+
+
+File formats
+------------
+
+The following executable file formats are supported:
+
+* <core/Shellcode.txt> (raw binary)
+* <core/PE.txt>/<core/COFF.txt> (32/64bits)
+* <core/ELF.txt> (32/64bits)
+
+Those are supported in a more limited way:
+
+* Mach-O, UniversalBinary
+* MZ
+* A.out
+* XCoff
+* NDS
+
+
+Features
+--------
+
+The framework includes
+
+* a graphical <usage/disassembler.txt>
+* a graphical <usage/debugger.txt>
+* low and high-level debugging support (Ia32 only for now) under Windows, Linux and remote (via a GdbServer)
+* an advanced disassembler engine, with limited emulation support
+* a full <usage/C_parser.txt> (with preprocessor)
+* an experimental <usage/C_compiler.txt> (Ia32 only)
+* an experimental <usage/decompiler.txt> (Ia32 only)
+

data/doc/index.txt

@@ -0,0 +1,59 @@
+The Metasm framework documentation
+==================================
+
+Metasm
+------
+
+The Metasm framework is an opensource software designed to interact with
+the various forms of binary code. It is written in pure Ruby
+(<http://ruby-lang.org/>).
+
+More detailed informations can be found in the <feature_list.txt>.
+
+It is distributed freely under the terms of the LGPL.
+
+Documentation organisation
+--------------------------
+
+This documentation is split in different parts :
+
+* the <core_classes.txt>
+* the major <use_cases.txt>
+* <code_organisation.txt>
+
+The first part describes the internal structure of the framework, the
+second part is a higher level overview of the software and shows how
+the various parts are used and can interract. The last part explains
+the role of the source files and directories.
+
+
+Documentation progress
+----------------------
+
+The documentation is written here and there in my free time, and is **very**
+**incomplete** as of now. Specifically, all internal links you'll find
+ending in `.txt` are link to pages that have not been written yet.
+
+
+Install notes
+-------------
+
+See the <install_notes.txt>
+
+Authors
+-------
+
+Metasm is mostly written by Yoann Guillot.
+
+Some parts were added by various contributors, including :
+* Julien Tinnès
+* Raphaël Rigo
+* Arnaud Cornet
+* Alexandre Gazet
+
+Contact
+-------
+
+The latest version of this documentation can be found on the Metasm site: <http://metasm.cr0.org/doc>
+
+Patches, bug reports, feature requests should be sent to metasm@cr0.org

data/doc/install_notes.txt

@@ -0,0 +1,170 @@
+Metasm installation notes
+=========================
+
+Metasm is a pure ruby lib, and the core (`metasm/` subdir) does not depend on any
+ruby library (except the `metasm/gui`, which may use `gtk2`).
+
+So the install is quite simple.
+
+
+Download
+--------
+
+Metasm is distributed using the `mercurial` source control system.
+
+The recommanded way to install is to use that tool, so you can always be
+up-to-date with the latest developpements.
+
+You will also need the Ruby interpreter (version 1.8 and 1.9 are supported).
+
+Linux
+#####
+
+Issue the following commands to install the `mercurial` and `ruby` software
+
+    sudo apt-get install ruby
+    sudo apt-get install mercurial
+
+Then download metasm with
+
+    hg clone http://metasm.cr0.org/hg/metasm/
+
+This will create a new directory `metasm/` with the latest version of the
+framework.
+
+
+Windows
+#######
+
+The ruby website offers many ruby packages. The *RubyInstaller* should
+work fine. Go to <http://www.ruby-lang.org/en/downloads/>, under the
+`Ruby on Windows` section.
+
+The `mercurial` website has links to various installers:
+<http://mercurial.selenic.com/wiki/BinaryPackages>
+Choose one, then use the `clone repository` command with the following
+url:
+
+    http://metasm.cr0.org/hg/metasm/
+
+This will create a new subdirectory `metasm/` with the latest version of
+the framework.
+
+
+Upgrading
+---------
+
+To upgrade to the latest and greatest version, launch a shell prompt and
+navigate to the metasm directory, then issue:
+
+    hg pull -u
+
+which will upgrade your installation to the latest available version.
+
+With `TortoiseHG`, simply issue the `upgrade` command on the `metasm`
+directory.
+
+
+Local installation
+------------------
+
+If you simply want to install metasm for your personnal usage (VS a
+system-wide installation), follow these steps.
+
+Download the metasm source files under any directory, then update the
+environment variable `RUBYLIB` to include this path. The path you add
+should be the directory containing the `metasm.rb` script and the `metasm/`,
+`samples/`, `doc/` subdirectories.
+
+If `RUBYLIB` is empty or non-existant, simply set its value to the directory,
+otherwise you can append the path to an existing list by separating the values
+with a `:` such as:
+
+  RUBYLIB='/foo/bar:/home/jj/metasm'
+
+Linux
+#####
+
+Under linux or cygwin, this is done by modifying your shell profile, e.g.
+`~/.bash_profile`, by adding a line such as:
+
+  export RUBYLIB='/home/jj/metasm'
+
+You may need to restart your session or start a new shell for the changes
+to take effect.
+
+Windows
+#######
+
+The environment variables can be set through :
+
+* rightclick on `my computer`
+* select tab `advanced`
+* click `environment variables`
+
+If a line RUBYLIB exists, add `;C:\path\to\metasm` at the end, otherwise
+create a new variable `RUBYLIB` with the path as value.
+
+You may need to restart your session for the changes to take effect.
+
+
+Systemwide installation
+-----------------------
+
+For a systemwide installation, you should create a `metasm.rb` file in the `site_ruby`
+directory (that would be `/usr/lib/ruby/1.8/` under linux, or `C:\apps\ruby\lib\ruby\1.8\`
+for windows users) with the content
+
+  # if metasm.rb can be found in /home/jj/metasm/metasm.rb
+  require '/home/jj/metasm/metasm'
+
+
+Testing
+-------
+
+Open a new shell session and type
+
+  ruby -r metasm -e "p Metasm::VERSION"
+
+It should print a single line with a (meaningless) number in it.
+
+
+Gui
+----
+
+If you intend to use the graphical user-interface (debugger/disassembler),
+if you are under Windows with a 32bit x86 ruby, this should work out of the
+box. In any other case, you'll need the `ruby-gtk2` library.
+
+Linux
+#####
+
+Under linux, use your package manager to install `ruby-gtk2`, e.g. for
+Debian/Ubuntu, type:
+
+    sudo apt-get install libgtk2-ruby
+
+
+Windows
+#######
+
+If you run a 32bit Ia32 ruby interpreter (check that `ruby -v` returns
+something like `[i386-mswin32]`), the Gui should work right away without
+`gtk2`, so go directly to the `Testing` part.
+
+Otherwise, you'll need to install the `gtk2` libs and the ruby bindings
+manually. Please follow the instructions at 
+<http://ruby-gnome2.sourceforge.jp/hiki.cgi?Install+Guide+for+Windows>
+
+
+Testing
+#######
+
+To test the correct working of the Gui, simply launch the
+`samples/disassemble-gui.rb` script found in the metasm directory
+(double-click on the script, or type `ruby samples/disassemble-gui.rb` at
+a command prompt). It should display a window with a menu, and should
+answer to a `ctrl-o` keystroke with an `open binary file` dialog.
+
+See the <usage/disassembler_gui.txt> for more information.
+

data/doc/style.css

@@ -0,0 +1,3 @@
+span.quote {
+	font-family: monospace;
+}

data/doc/use_cases.txt

@@ -0,0 +1,18 @@
+Metasm use cases
+================
+
+Metasm is intended to be a binary manipulation toolbox.
+There are quite a lot of possible usages that can be derived from the
+<feature_list.txt>.
+
+The major would be related to:
+
+* the scriptable <usage/debugger.txt>
+* the <usage/disassembler.txt> (with the optionnal <usage/disassembler_gui.txt>)
+* the <usage/assembler.txt>
+* the <usage/C_parser.txt>
+* the <usage/C_compiler.txt>
+* the <usage/exe_manipulation.txt> facilities
+
+and various interaction between those.
+

data/lib/metasm.rb

@@ -0,0 +1,80 @@
+#    This file is part of Metasm, the Ruby assembly manipulation suite
+#    Copyright (C) 2006-2009 Yoann GUILLOT
+#
+#    Licence is LGPL, see LICENCE in the top-level directory
+
+
+module Metasm
+	# root directory for metasm files
+	# used by some scripts, eg to find samples/dasm-plugin directory
+	Metasmdir = File.dirname(__FILE__)
+	# add it to the ruby library path
+	$: << Metasmdir
+
+	# constants defined in the same file as another
+	Const_autorequire_equiv = {
+		'X86' => 'Ia32', 'PPC' => 'PowerPC',
+		'X64' => 'X86_64', 'AMD64' => 'X86_64',
+		'UniversalBinary' => 'MachO', 'COFFArchive' => 'COFF',
+		'DEY' => 'DEX',
+		'PTrace' => 'LinOS', 'FatELF' => 'ELF',
+		'LoadedELF' => 'ELF', 'LoadedPE' => 'PE',
+		'LoadedAutoExe' => 'AutoExe',
+		'LinuxRemoteString' => 'LinOS',
+		'LinDebugger' => 'LinOS',
+		'WinAPI' => 'WinOS',
+		'WindowsRemoteString' => 'WinOS', 'WinDbgAPI' => 'WinOS',
+		'WinDebugger' => 'WinOS',
+		'GdbRemoteString' => 'GdbClient', 'GdbRemoteDebugger' => 'GdbClient',
+		'DecodedInstruction' => 'Disassembler', 'DecodedFunction' => 'Disassembler',
+		'InstructionBlock' => 'Disassembler',
+	}
+
+	# files to require to get the definition of those constants
+	Const_autorequire = {
+		'Ia32' => 'ia32', 'MIPS' => 'mips', 'PowerPC' => 'ppc', 'ARM' => 'arm',
+		'X86_64' => 'x86_64', 'Sh4' => 'sh4', 'Dalvik' => 'dalvik',
+		'C' => 'compile_c',
+		'MZ' => 'exe_format/mz', 'PE' => 'exe_format/pe',
+		'ELF' => 'exe_format/elf', 'COFF' => 'exe_format/coff',
+		'Shellcode' => 'exe_format/shellcode', 'AutoExe' => 'exe_format/autoexe',
+		'AOut' => 'exe_format/a_out', 'MachO' => 'exe_format/macho',
+		'DEX' => 'exe_format/dex',
+		'NDS' => 'exe_format/nds', 'XCoff' => 'exe_format/xcoff',
+		'Bflt' => 'exe_format/bflt', 'Dol' => 'exe_format/dol',
+		'Gui' => 'gui',
+		'WindowsExports' => 'os/windows_exports',
+		'GNUExports' => 'os/gnu_exports',
+		'LinOS' => 'os/linux', 'WinOS' => 'os/windows',
+		'GdbClient' => 'os/remote',
+		'Disassembler' => 'disassemble',
+		'Decompiler' => 'decompile',
+		'DynLdr' => 'dynldr',
+	}
+
+	# use the Module.autoload ruby functionnality to load framework components on demand
+	Const_autorequire.each { |cst, file|
+		autoload cst, File.join('metasm', file)
+	}
+
+	Const_autorequire_equiv.each { |cst, eqv|
+		file = Const_autorequire[eqv]
+		autoload cst, File.join('metasm', file)
+	}
+end
+
+# load Metasm core files
+%w[main encode decode render exe_format/main os/main].each { |f|
+	require File.join('metasm', f)
+}
+
+
+# remove an 1.9 warning, couldn't find a compatible way...
+if Hash.new.respond_to?(:key)
+	puts "using ruby1.9 workaround for Hash#index warning" if $DEBUG
+	class Hash
+		alias index_premetasm index rescue nil
+		undef index rescue nil
+		alias index key
+	end
+end