+
+On the Intel architecture numbers are represented *little endian* meaning lower
+significant bytes are stored in lower memory addresses. The whole memory
+representation for a value is partitioned into *high bits* and *low bits*. For
+example the hexadecimal number ``0xc0ffee`` as a DWORD is stored in memory as:
+
+
+
+In Haskell unboxed integral machine types are provided by the ``Data.Word``
+[module](https://hackage.haskell.org/package/base-4.8.1.0/docs/Data-Word.html).
+
+```haskell
+data Word8 = W8# Word#
+data Word16 = W16# Word#
+data Word32 = W32# Word#
+data Word64 = W64# Word#
+```
+
+Pointers are simply literal addresses to main memory, where the underlying
+access and storage are managed by the Linux kernel. To model this abstractly in
+Haskell we'll create a datatype containing the possible values we can operate
+over.
+
+```haskell
+data Val
+ = I Int64 -- Integer
+ | R Reg -- Register
+ | A Word32 -- Addr
+ deriving (Eq, Show)
+```
+
+To convert from Haskell types into byte sequences we'll use the binary library
+to convert integral types into little endian arrays of bytes.
+
+```haskell
+bytes :: Integral a => a -> [Word8]
+bytes x = fmap BS.c2w bs
+ where
+ bs = unpack $ runPut $ putWord32le (fromIntegral x)
+```
+
+For example given a hexadecimal literal this will expand it out into an array of
+it's bit components.
+
+```haskell
+val = bytes 0xc0ffee -- [238,255,192,0]
+```
+
+#### Registers
+
+The x64 architecture contains sixteen general purpose 64-bit registers capable
+of storing a quadword. They major ones are labeled ``rax, rbx, rcx, rdx, rbp,
+rsi, rdi,`` and ``rsp``.
+
+Each of the registers is given a specific index (``r``), which will be used in
+the binary representation of specific instructions that operate over these
+registers.
+
+ RAX RBX RCX RDX RBP RSI RDI RSP
+--- --- --- --- --- --- --- --- ----
+r = 0 1 2 3 4 5 6 7
+
+
+Each of these registers can be addressed as a smaller register containing a
+subset of the lower bits. The 32-bit register of ``rax`` is ``eax``. These are
+shown in the table below.
+
+
+
+These smaller registers are given specific names with modified prefixes.
+
+64-bit 32-bit 16-bit
+--- --- --
+rax eax ax
+rbx ebx bx
+rcx ecx cx
+rdx edx dx
+rsp esp sp
+rbp ebp bp
+rsi esi si
+rdi edi di
+rip eip ip
+
+In Haskell we model this a sum type for each of the 64-bit registers. Consider
+just the 64-bit registers for now.
+
+```haskell
+data Reg
+ = RAX -- Accumulator
+ | RCX -- Counter (Loop counters)
+ | RDX -- Data
+ | RBX -- Base / General Purpose
+ | RSP -- Current stack pointer
+ | RBP -- Previous Stack Frame Link
+ | RSI -- Source Index Pointer
+ | RDI -- Destination Index Pointer
+ deriving (Eq, Show)
+```
+
+The index for each register is defined by a simple pattern match case
+expression.
+
+```haskell
+index :: Reg -> Word8
+index x = case x of
+ RAX -> 0
+ RCX -> 1
+ RDX -> 2
+ RBX -> 3
+ RSP -> 4
+ RBP -> 5
+ RSI -> 6
+ RDI -> 7
+```
+
+#### Monads
+
+Monads are an algebraic structure with two functions (``bind``) and (``return``)
+and three laws.
+
+```haskell
+bind :: Monad m => m a -> (a -> m b) -> m b
+return :: Monad m => a -> m a
+```
+
+The compiler will desugar do-blocks of the form into a canonical form involving
+generic bind and return statements.
+
+```haskell
+f :: Monad m => m Int
+f = do
+ a <- x
+ b <- y
+ return (a+b)
+```
+
+Is transformed into:
+
+```haskell
+f :: Monad m => m Int
+f =
+ bind x (\a ->
+ bind y (\b ->
+ return (a+b))
+```
+
+Monad is implemented as a typeclass indexed by a parameter ``m``, that when
+instantiated with a typeclass instances replaces the bind and return functions
+with a specific implementation of the two functions (like State or Reader).
+
+```haskell
+f :: State MyState Int
+f =
+ bindState x (\a ->
+ bindState y (\b ->
+ returnState (a+b))
+```
+
+The State monad is an instance of Monad with several functions for composing
+stateful logic.
+
+```haskell
+get :: State s s -- get the state
+put :: s -> State s () -- set the state
+modify :: (s -> s) -> State s () -- apply a function over the state
+```
+
+For example a little state machine that holds a single Int value would be
+written like the following.
+
+```haskell
+machine :: State Int Int
+machine = do
+ put 3
+ modify (+1)
+ get
+
+val :: Int
+val = execState machine 0
+```
+
+More common would be to have the state variable ``s`` be a record with multiple
+fields that can be modified. For managing our JIT memory we'll create a struct
+with the several fields.
+
+```haskell
+data JITMem = JITMem
+ { _instrs :: [Instr]
+ , _mach :: [Word8]
+ , _icount :: Word32
+ , _memptr :: Word32
+ , _memoff :: Word32
+ } deriving (Eq, Show)
+```
+
+This will be composed into our X86 monad which will hold the JIT memory as we
+assemble individual machine instructions and the pointer and memory offsets for
+the sequence of assembled instructions.
+
+```haskell
+type X86 a = StateT JITMem (Except String) a
+```
+
+#### JIT Memory
+
+To start creating the JIT we first need to create a block of memory with
+executable permissions. Inside of [C
+runtime](https://sourceware.org/git/?p=glibc.git;a=blob;f=bits/mman.h;h=1d9f6f8d9caba842983f98ff2f2dd5a776df054c;hb=HEAD#l32)
+we can get the flags needed to be passed to the various ``mmap`` syscall to
+create the necessary memory block.
+
+```cpp
+#define PROT_NONE 0x00 /* No access. */
+#define PROT_READ 0x04 /* pages can be read */
+#define PROT_WRITE 0x02 /* pages can be written */
+#define PROT_EXEC 0x01 /* pages can be executed */
+
+#define MAP_FILE 0x0001 /* mapped from a file or device */
+#define MAP_ANON 0x0002 /* allocated from memory, swap space */
+#define MAP_TYPE 0x000f /* mask for type field */
+```
+
+Then we simply allocate a given block of memory off the Haskell heap via mmap
+with the executable flags.
+
+```haskell
+newtype MmapOption = MmapOption CInt
+ deriving (Eq, Show, Ord, Num, Bits)
+
+protExec = ProtOption 0x01
+protWrite = ProtOption 0x02
+mmapAnon = MmapOption 0x20
+mmapPrivate = MmapOption 0x02
+
+allocateMemory :: CSize -> IO (Ptr Word8)
+allocateMemory size = mmap nullPtr size pflags mflags (-1) 0
+ where
+ pflags = protRead <> protWrite
+ mflags = mapAnon .|. mapPrivate
+```
+
+Haskell pointers can be passed to our JIT'd code by simply casting them into
+their respective addresses on the Haskell heap.
+
+```haskell
+heapPtr :: Ptr a -> Word32
+heapPtr = fromIntegral . ptrToIntPtr
+```
+
+For example if we want allocate a null-terminated character array and pass a
+pointer to it's memory to our JIT'd code we can write down a ``asciz`` to
+synthesize this memory from a Haskell string and grab the heap pointer.
+
+```haskell
+asciz :: [Char] -> IO Word32
+asciz str = do
+ ptr <- newCString (str ++ ['\n'])
+ return $ heapPtr ptr
+```
+
+For C functions we simply use the dynamic linker to grab the function pointer
+the given symbol in the memory space of the process. The Haskell runtime links
+against glibc's ``stdio.h`` and ``math.h`` so these symbols will all be floating
+around in memory.
+
+```haskell
+extern :: String -> IO Word32
+extern name = do
+ dl <- dlopen "" [RTLD_LAZY, RTLD_GLOBAL]
+ fn <- dlsym dl name
+ return $ heapPtr $ castFunPtrToPtr fn
+```
+
+When we've compiled our byte vector of machine code we'll copy into executable
+memory.
+
+```haskell
+jit :: Ptr Word8 -> [Word8] -> IO (IO Int)
+jit mem machCode = do
+ code <- codePtr machCode
+ withForeignPtr (vecPtr code) $ \ptr -> do
+ copyBytes mem ptr (8*6)
+ return (getFunction mem)
+```
+
+Then we'll use the FFI to synthesize a function pointer to the memory and invoke
+it.
+
+```haskell
+foreign import ccall "dynamic"
+ mkFun :: FunPtr (IO Int) -> IO Int
+
+getFunction :: Ptr Word8 -> IO Int
+getFunction mem = do
+ let fptr = unsafeCoerce mem :: FunPtr (IO Int)
+ mkFun fptr
+```
+
+#### Assembly
+
+Before we start manually populating our executable code with instructions, let's
+look at *assembly* form of what we'll write and create a small little DSL in
+Haskell make this process closer to the problem domain. Assembly is the
+intermediate human readable representation of machine code. Both clang and gcc
+are capable of dumping out this representation before compilation. For example
+for the following C program takes two integers passed in registers, multiplies
+ them respectively and adds the result.
+
+```cpp
+int f(int x, int y)
+{
+ return (x*x)^y;
+}
+```
+
+Internally the C compiler is condensing the Destructuring the expressions into a
+linear sequence instructions storing the intermediate results in scratch
+registers and writing the end computed result to return register. It then
+selects appropriate machine instruction for each of the abstract operations.
+
+```cpp
+// pseudocode for intermediate C representation
+int f() {
+ int x = register(rdi);
+ int y = register(rsi);
+ int tmp1 = x*x;
+ int tmp2 = tmp1^y;
+ return tmp2;
+}
+```
+
+We can output the assembly to a file ``add.s``. We'll use the Intel Syntax which
+puts the destination operand before other operands. The alternate AT&T syntax
+reverses this convention.
+
+```bash
+$ clang -O2 -S --x86-asm-syntax=intel xor.c
+```
+
+The generated code will resemble the following. Notice that there are two kinds
+of statements: *directives* and *instructions*. Directive are prefixed with a
+period while instructions are an operation together with a list operands.
+Statements of instructions are grouped into labeled blocks are suffixed with a
+colon for example ``f:`` is the label containing the logic for the function
+``f``.
+
+```perl
+ .file "xor.c"
+ .text
+ .globl f
+ .type f, @function
+ .intel_syntax noprefix
+f:
+ mov eax, edi
+ imul eax, edi
+ xor eax, esi
+ ret
+```
+
+The assembler will then turn this sequence of instructions into either an
+executable or an object file containing the generated machine code. To
+disassemble the output we can use objdump to view the hex sequence of machine
+instructions and the offsets within the file.
+
+```bash
+$ objdump -M intel -d xor.o
+
+xor: file format elf64-x86-64
+
+Disassembly of section .text:
+
+0000000000000000 
+
+
+
+The sizes of these parts depend on the size and type of the opcode as well as
+prefix modifiers.
+
+Prefix Opcode Mod R/M Scale Index Base Displacement Immediate
+------ ------ ------- ----------------- ------------ ---------
+1-4 bytes 1-3 bytes 1 Byte 1 Byte 1-4 Bytes 1-4 Bytes
+
++ +**Prefix** + +
+
+The header fixes the first four bits to be constant ``0b0100`` while the next
+four bits indicate the pretense of W/R/X/B extensions.
+
+The W bit modifies the operation width. The R, X and B fields extend the register encodings.
+
+* REX.W -- Extends the operation width
+* REX.R -- Extends ModRM.reg
+* REX.X -- Extends SIB.index
+* REX.B -- Extends SIB.base or ModRM.r/m
+
+
+
++ +**ModR/M byte** + +
+
+The Mod-Reg-R/M byte determines the instruction's operands and the addressing
+modes. These are several variants of addressing modes.
+
+1. Immediate mode - operand is part of the instruction
+2. Register addressing - operand contained in register
+3. Direct Mode - operand field of instruction contains address of the operand
+4. Register Indirect Addressing - used for addressing data arrays with offsets
+5. Indexing - constant base + register
+6. Indexing With Scaling - Base + Register Offset * Scaling Factor
+7. Stack Addressing - A variant of register indirect with auto increment/decrement using the RSP register implicitly
+8. Jump relative addressing - RIP + offset
+
+
+
+mod meaning
+--- ------------------------------------------
+00 Register indirect memory addressing mode
+01 Indexed or base/indexed/displacement addressing mode
+10 Indexed or base/indexed/displacement addressing mode + displacement
+11 R/M denotes a register and uses the REG field
+
+reg
+--- ---
+rax 000
+rcx 001
+rdx 010
+rbx 011
+rsp 100
+rbp 101
+rsi 110
+rdi 111
+
+In the case of mod = 00, 01 or 10
+
+r/m meaning
+--- --------
+000 [BX+SI] or DISP[BX][SI]
+001 [BX+DI] or DISP[BX+DI]
+010 [BP+SI] or DISP[BP+SI]
+011 [BP+DI] or DISP[BP+DI]
+100 [SI] or DISP[SI]
+101 [DI] or DISP[DI]
+110 Displacement-only or DISP[BP]
+111 [BX] or DISP[BX]
+
+For example given the following instruction that uses register direct mode and
+specifies the register operand in r/m.
+
+```perl
+mov rbx,rax
+```
+
+We have:
+
+```
+mod = 0b11
+reg = 0b000
+r/m = rbx
+r/m = 0b011
+ModRM = 0b11000011
+ModRM = 0xc3
+```
+
+
+
++ +**Scale Index Base** + +
+
+Scale is the factor by which index is multipled before being added to base to
+specify the address of the operand. Scale can have value of 1, 2, 4, or
+8. If scale is not specified, the default value is 1.
+
+
+
+scale factor
+----- ------
+0b00 1
+0b01 2
+0b10 4
+0b11 8
+
+Both the index and base refer to register in the usual index scheme.
+
+scale/base
+--- ---
+rax 000
+rcx 001
+rdx 010
+rbx 011
+rsp 100
+rbp 101
+rsi 110
+rdi 111
+
++ +#### Instruction Builder + +Moving forward we'll create several functions mapping to X86 monadic operators +which assemble instructions in the state monad. Let's do some simple arithmetic +logic first. + +```haskell +arith :: X86 () +arith = do + mov rax (I 18) + add rax (I 4) + sub rax (I 2) + imul rax (I 2) + ret +``` + +Each of these functions takes in some set of operands given by the algebraic +datatype ``Val`` and pattern matches on the values to figure out which x86 +opcode to use and how to render the values to bytes. + +**``ret``** + +The simplest cases is simply the return function which takes no operands and is +a 1-bit opcode. + +```haskell +ret :: X86 () +ret = do + emit [0xc3] +``` + +**``add