README

   1                                                               -*-outline-*-
   2 * README file for the Harpy Haskell Run-time Code Generator
   3
   4 Codename: Harpy - Haskell Assembler at Run-time produces Y...
   5   Harpy [myth.] f: die Harpyie
   6   http://en.wikipedia.org/wiki/Harpy
   7
   8 ** Introduction
   9
  10 Harpy is a library for run-time code generation in Haskell programs.
  11
  12 Harpy requires several Haskell extensions and GHC-specific features
  13 (the Haskell FFI, Template Haskell, multi-parameter type classes and
  14 monad transformers).
  15
  16 ** Features
  17
  18 The following modules are included in this package:
  19
  20 Harpy.CodeGenMonad: This module defines the code generator monad,
  21   which is a combined state/reader/exception monad.  It contains
  22   all the necessary details for allocating and managing code buffers.
  23
  24 Harpy.X86CodeGen: This module contains all the functions for generating
  25   native x86 machine code.  The functions are very simple, and it is
  26   necessary to specify all addressing modes etc. when emitting an
  27   instruction.
  28
  29 Harpy.X86Assembler: A type class based layer on top of X86CodeGen
  30   which determines the addressing modes from the types of the
  31   operands.
  32
  33 Harpy.X86CGCombinators: Code generation combinators for conditionals,
  34   loops, function entry/exit code etc.
  35
  36 Harpy.X86Disassembler: A disassembler for x86 machine code.
  37
  38 Harpy.Call: Exports functions for invoking the generated code.
  39
  40 ** Notes about the implementation
  41
  42 *** X86CodeGen.lhs
  43
  44 The file X86CodeGen.lhs is based on a header file called x86-codegen.h
  45 from the Mono distribution, which defines macros for emitting x86
  46 machine code directly into a memory buffer.  The Haskell module is a
  47 nearly one-to-one mapping from the original macros to Haskell
  48 functions.  The main differences are:
  49
  50 - Instead of emitting the data directly into a buffer, it uses the
  51   CodeGen monad from file CodeGenMonad.lhs.
  52
  53 - The functions are strongly typed.
  54
  55 Several things should be kept in mind when using this file:
  56
  57 - Buffer overflow checks have to be done manually with checkBufferSize or
  58   ensureBufferSize
  59
  60 - MMX, SSE, SSE2 and SSE3 instructions and registers are not supported.
  61
  62 - 64-bit mode is not supported.
  63
  64 - The disassembler supports (in principle) 64-bit mode and SSE
  65   instructions, but this has not been tested.