Harpy.CodeGenMonad

Monad for generating x86 machine code at runtime.

This is a combined reader-state-exception monad which handles all the details of handling code buffers, emitting binary data, relocation etc.

All the code generation functions in module Harpy.X86CodeGen live in this monad and use its error reporting facilities as well as the internal state maintained by the monad.

The library user can pass a user environment and user state through the monad. This state is independent from the internal state and may be used by higher-level code generation libraries to maintain their own state across code generation operations. --------------------------------------------------------------------------

Types

data CodeGen e s a

The code generation monad, a combined reader-state-exception monad.

Instances

Monad (CodeGen e s)

Functor (CodeGen e s)

Applicative (CodeGen e s)

MonadIO (CodeGen e s)

type ErrMsg = Doc

An error message produced by a code generation operation.

data RelocKind

Kind of relocation, for example PC-relative

Constructors

RelocPCRel

PC-relative relocation

RelocAbsolute

Absolute address

Instances

Show RelocKind

data Reloc

Relocation entry

Instances

Show Reloc

data Label

Label

Instances

Eq Label

Ord Label

Call Label

Js Label

Jo Label

Jns Label

Jno Label

Jnle Label

Jnl Label

Jnge Label

Jng Label

Jle Label

Jl Label

Jge Label

Jg Label

Jz Label

Jpo Label

Jpe Label

Jp Label

Jnz Label

Jnp Label

Jne Label

Jnc Label

Jnbe Label

Jnb Label

Jnae Label

Jna Label

Je Label

Jc Label

Jbe Label

Jb Label

Jae Label

Ja Label

Jmp Label

Loop Label

Push Label

Mov Ind Label

Mov Addr Label

Mov Reg32 Label

Cmp Ind Label

Cmp Addr Label

Cmp Reg32 Label

Mov (Disp, Reg32) Label

Cmp (Disp, Reg32) Label

Mov (Disp, Reg32, Scale) Label

Mov (Reg32, Reg32, Scale) Label

Mov (Disp, Reg32, Reg32, Scale) Label

data FixupKind

Kind of a fixup entry. When a label is emitted with defineLabel, all prior references to this label must be fixed up. This data type tells how to perform the fixup operation.

Constructors

Fixup8

8-bit relative reference

Fixup16

16-bit relative reference

Fixup32

32-bit relative reference

Fixup32Absolute

32-bit absolute reference

Instances

Show FixupKind

data CodeGenConfig

Configuration of the code generator. There are currently two configuration options. The first is the number fo bytes to use for allocating code buffers (the first as well as additional buffers created in calls to ensureBufferSize. The second allows to pass in a pre-allocated code buffer and its size. When this option is used, Harpy does not perform any code buffer resizing (calls to ensureBufferSize will be equivalent to calls to checkBufferSize).

Constructors

CodeGenConfig

Fields

codeBufferSize :: Int

Size of individual code buffer blocks.

customCodeBuffer :: Maybe (Ptr Word8, Int)

Code buffer passed in.

defaultCodeGenConfig :: CodeGenConfig

Default code generation configuration. The code buffer size is set to 4KB, and code buffer management is automatic. This value is intended to be used with record update syntax, for example:

 runCodeGenWithConfig ... defaultCodeGenConfig{codeBufferSize = 128} ...

Functions

General code generator monad operations

failCodeGen :: Doc -> CodeGen e s a

Abort code generation with the given error message.

Accessing code generation internals

getEntryPoint :: CodeGen e s (Ptr Word8)

Return a pointer to the beginning of the first code buffer, which is normally the entry point to the generated code.

getCodeOffset :: CodeGen e s Int

Return the current offset in the code buffer, e.g. the offset at which the next instruction will be emitted.

getBasePtr :: CodeGen e s (Ptr Word8)

Return the pointer to the start of the code buffer.

getCodeBufferList :: CodeGen e s [(Ptr Word8, Int)]

Return a list of all code buffers and their respective size (i.e., actually used space for code, not allocated size).

Access to user state and environment

setState :: s -> CodeGen e s ()

Set the user state to the given value.

getState :: CodeGen e s s

Return the current user state.

getEnv :: CodeGen e s e

Return the current user environment.

withEnv :: e -> CodeGen e s r -> CodeGen e s r

Set the environment to the given value and execute the given code generation in this environment.

Label management

newLabel :: CodeGen e s Label

Generate a new label to be used with the label operations emitFixup and defineLabel.

newNamedLabel :: String -> CodeGen e s Label

Generate a new label to be used with the label operations emitFixup and defineLabel. The given name is used for diagnostic purposes, and will appear in the disassembly.

setLabel :: CodeGen e s Label

Generate a new label and define it at once

defineLabel :: Label -> CodeGen e s ()

Emit a label at the current offset in the code buffer. All references to the label will be relocated to this offset.

(@@) :: Label -> CodeGen e s a -> CodeGen e s a

This operator gives neat syntax for defining labels. When l is a label, the code

l @@ mov eax ebx

associates the label l with the following mov instruction.

emitFixup :: Label -> Int -> FixupKind -> CodeGen e s ()

Emit a fixup entry for the given label at the current offset in the code buffer (unless the label is already defined). The instruction at this offset will be patched to target the address associated with this label when it is defined later.

labelAddress :: Label -> CodeGen e s (Ptr a)

Return the address of a label, fail if the label is not yet defined.

emitRelocInfo :: Int -> RelocKind -> FunPtr a -> CodeGen e s ()

Emit a relocation entry for the given offset, relocation kind and target address.

Code emission

emit8 :: Word8 -> CodeGen e s ()

Emit a byte value to the code buffer.

emit8At :: Int -> Word8 -> CodeGen e s ()

Store a byte value at the given offset into the code buffer.

peek8At :: Int -> CodeGen e s Word8

Return the byte value at the given offset in the code buffer.

emit32 :: Word32 -> CodeGen e s ()

Like emit8, but for a 32-bit value.

emit32At :: Int -> Word32 -> CodeGen e s ()

Like emit8At, but for a 32-bit value.

checkBufferSize :: Int -> CodeGen e s ()

Check whether the code buffer has room for at least the given number of bytes. This should be called by code generators whenever it cannot be guaranteed that the code buffer is large enough to hold all the generated code. Lets the code generation monad fail when the buffer overflows.

Note: Starting with version 0.4, Harpy automatically checks for buffer overflow, so you do not need to call this function anymore.

ensureBufferSize :: Int -> CodeGen e s ()

Make sure that the code buffer has room for at least the given number of bytes. This should be called by code generators whenever it cannot be guaranteed that the code buffer is large enough to hold all the generated code. Creates a new buffer and places a jump to the new buffer when there is not sufficient space available. When code generation was invoked with a pre-defined code buffer, code generation is aborted on overflow.

Note: Starting with version 0.4, Harpy automatically checks for buffer overflow, so you do not need to call this function anymore.

Executing code generation

runCodeGen :: CodeGen e s a -> e -> s -> IO (s, Either ErrMsg a)

Execute code generation, given a user environment and state. The result is a tuple of the resulting user state and either an error message (when code generation failed) or the result of the code generation. This function runs runCodeGenWithConfig with a sensible default configuration.

runCodeGenWithConfig :: CodeGen e s a -> e -> s -> CodeGenConfig -> IO (s, Either ErrMsg a)

Like runCodeGen, but allows more control over the code generation process. In addition to a code generator and a user environment and state, a code generation configuration must be provided. A code generation configuration allows control over the allocation of code buffers, for example.

Calling generated functions

callDecl :: String -> Q Type -> Q [Dec]

Interface to disassembler

disassemble :: CodeGen e s [Instruction]

Disassemble all code buffers. The result is a list of disassembled instructions which can be converted to strings using the showIntel or showAtt functions from module Harpy.X86Disassembler.