|
| Harpy.CodeGenMonad | | Portability | portable (but generated code non-portable) | | Stability | provisional | | Maintainer | {magr,klee}@cs.tu-berlin.de |
|
|
|
|
|
| Description |
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.
--------------------------------------------------------------------------
|
|
| Synopsis |
|
|
|
|
| Types
|
|
|
| The code generation monad, a combined reader-state-exception
monad.
|  Instances | |
|
|
|
| An error message produced by a code generation operation.
|
|
|
| Kind of relocation, for example PC-relative
| | Constructors | | RelocPCRel | PC-relative relocation
| | RelocAbsolute | Absolute address
|
| | Instances | |
|
|
|
| Relocation entry
| | Instances | |
|
|
|
| Label
| | Instances | |
|
|
|
| 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 | |
|
|
|
| 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 | | | codeBufferSize :: Int | Size of individual code buffer blocks.
| | customCodeBuffer :: Maybe (Ptr Word8, Int) | Code buffer passed in.
|
|
|
|
|
|
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
|
|
|
| Abort code generation with the given error message.
|
|
| Accessing code generation internals
|
|
|
| Return a pointer to the beginning of the first code buffer, which
is normally the entry point to the generated code.
|
|
|
| Return the current offset in the code buffer, e.g. the offset
at which the next instruction will be emitted.
|
|
|
| Return the pointer to the start of the code buffer.
|
|
|
| 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
|
|
|
| Set the user state to the given value.
|
|
|
| Return the current user state.
|
|
|
| Return the current user environment.
|
|
|
| Set the environment to the given value and execute the given
code generation in this environment.
|
|
| Label management
|
|
|
| Generate a new label to be used with the label operations
emitFixup and defineLabel.
|
|
|
| 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.
|
|
|
| Generate a new label and define it at once
|
|
|
| Emit a label at the current offset in the code buffer. All
references to the label will be relocated to this offset.
|
|
|
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.
|
|
|
| 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.
|
|
|
| Return the address of a label, fail if the label is not yet defined.
|
|
|
| Emit a relocation entry for the given offset, relocation kind
and target address.
|
|
| Code emission
|
|
|
| Emit a byte value to the code buffer.
|
|
|
| Store a byte value at the given offset into the code buffer.
|
|
|
| Return the byte value at the given offset in the code buffer.
|
|
|
| Like emit8, but for a 32-bit value.
|
|
|
| Like emit8At, but for a 32-bit value.
|
|
|
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.
|
|
|
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
|
|
|
| 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.
|
|
|
| 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
|
|
|
|
| Interface to disassembler
|
|
|
| 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.
|
|
| Produced by Haddock version 2.1.0 |
