Building a CPU with Haskell

Part 1

October 2017

Today, we're going to build a simple CPU. We're going to write it in Haskell and use CLaSH to compile it to hardware.

This entire webpage is a literate Haskell file. You can see it here on Github.

To load the file into an interactive REPL, install CLaSH and run clashi CPU1.lhs .

If you want to simulate the Verilog hardware code or put it on an FPGA, there are more detailed instructions towards the end of the tutorial.

About This CPU

This CPU design is an extremely simple serial state machine. It's easily 5-10x slower than an optimized CPU running at the same clock rate. We'll start with this simple design to get a handle on the problem, and switch to more complicated (but faster) designs in later installments.

We will also pretend that RAM access is instantaneous. We will deal with realistic RAM in later installments.

The fact that we're writing this CPU in Haskell instead of in an HDL like Verilog means that there will be substantial stylistic differences from how CPUs are normally written. However, almost all of these differences make it vastly simpler and faster to write hardware. The downside is that the generated hardware isn't (yet) as space-efficient as expertly hand-rolled circuitry. It's sort of like the difference between writing optimized assembly by hand versus using a high-level language. Hopefully as compiler technology improves, we can close the efficiency gap, save a lot of human labor, and write less buggy hardware.

The Code

Imports

First we're just going to import a bunch of stuff.

-- Allows the compiler to auto-write code for wrapper types. {-# LANGUAGE GeneralizedNewtypeDeriving #-} -- The name of our module module CPU1 where -- CLaSH-provided hardware stuff import CLaSH.Sized.Unsigned ( Unsigned ) import CLaSH.Sized.Vector ( Vec ((:>), Nil ), ( !! ), replace, repeat, ( ++ )) import CLaSH.Class.Resize (zeroExtend) import CLaSH.Sized.BitVector ( BitVector , (++#), Bit ) import CLaSH.Class.BitPack (pack, unpack) import CLaSH.Prelude (slice) import CLaSH.Promoted.Nat.Literals as Nat import CLaSH.Signal ( Signal , register, sample) -- Plain old Haskell stuff import Prelude ((+), (-), (*), (==), ($), (.), filter, take, fmap, not, error, Show , Bool ( True , False ), Maybe ( Just , Nothing )) -- Used to make sure that something is fully evaluated. -- Good for making sure that our circuit -- doesn't have any undefined behavior by forcing the full -- evaluation of outputs. import Control.DeepSeq ( NFData )

Some CPU-related Types

Our CPU will have 4 64-bit registers. We'll identify them by a register number.

data Register = R1 | R2 | R3 | R4 deriving Show

We'll define a wrapper type for 64-bit memory addresses:

newtype Ptr = Ptr ( Unsigned 64 ) deriving ( Show )

A wrapper type for 64-bit memory words:

newtype Word = Word ( Unsigned 64 ) deriving Show

As well as a wrapper type for 64-bit I/O output:

-- Making Output an instance of NFData allows CLaSH -- to force full evaluation during testing. newtype Output = Output ( Unsigned 64 ) deriving ( Show , NFData )

These all have the same underlying 64-bit representation, so the wrapper is just to help us keep track of whether something is a value or a pointer to a value or whatever.

Instruction Set

Let's define our instruction set. The first instruction is to load a 56-bit immediate value into a register.

data Instruction = LoadIm Register ( Unsigned 56 )

The second instruction is to add two registers and put the result into a third register.

| Add Register Register Register

And the same for subtraction and multiplication:

| Sub Register Register Register | Mul Register Register Register

Next, we'll add memory load and stores. The first argument is the source or destination register, and the second argument is the register that holds the pointer to memory.

| Load Register Register | Store Register Register

We'll add an unconditional and conditional branch. For the unconditional branch, the CPU jumps to the address in the register. For the conditional branch, if the first register is equal to zero, the CPU jumps to the address in the second register.

| Jmp Register | JmpZ Register Register

We'll add an "Output" instruction, which will output a register's contents through the 64-bit IO port.

| Out Register

Finally, we'll add a "Halt" instruction, which will halt the CPU.

| Halt deriving Show

CPU State and RAM

Next, we'll define all the possible states of our CPU:

data CPUActivity = LoadingInstruction | ExecutingInstruction Instruction | ReadingMemory Ptr Register | WritingMemory Ptr Word | Outputting Output | Halted

As well as the state of our CPU registers:

data Registers = Registers { r1 :: Unsigned 64 , r2 :: Unsigned 64 , r3 :: Unsigned 64 , r4 :: Unsigned 64 , pc :: Ptr }

The total state of our CPU is the combination of those two things.

data CPUState = CPUState CPUActivity Registers

We're also going to have a 512B internal "RAM" which can finish a read or write request in the same cycle it was dispatched. You can do this in real hardware, but it is fairly expensive and slows down your maximum clock rate by a lot. Real internal RAM takes at least one cycle to complete an operation, and external RAM usually takes multiple cycles. We'll deal with that in the next installment.

data RAM = RAM ( Vec 64 Word )

We'll write a few helper functions that let us perform basic state operations, like reading and writing from registers and RAM.

readRegister :: Registers -> Register -> Unsigned 64 readRegister ( Registers reg1 reg2 reg3 reg4 _) reg = case reg of R1 -> reg1 R2 -> reg2 R3 -> reg3 R4 -> reg4 writeRegister :: Registers -> Register -> Unsigned 64 -> Registers writeRegister regs reg word = case reg of R1 -> regs {r1 = word} R2 -> regs {r2 = word} R3 -> regs {r3 = word} R4 -> regs {r4 = word}

readRAM :: RAM -> Ptr -> Word readRAM ( RAM contents) ( Ptr address) = contents !! address writeRAM :: RAM -> Ptr -> Word -> RAM writeRAM ( RAM contents) ( Ptr address) val = RAM (replace address val contents) increment :: Ptr -> Ptr increment ( Ptr address) = Ptr (address + 1 )

Machine Code Format

Now we have to write code to encode and decode instructions to/from a 64-bit binary machine code format.

The format is very simple:

The first 4 bits are the instruction ID ("tag")

The second, third, fourth 4 bits are register numbers. We could use 2 bits (as we only have 4 registers), but I'm leaving room for more registers later.

The last 56 bits are the immediate value, in the case of LoadIm .

encodeInstruction :: Instruction -> Word encodeInstruction instr = Word $ unpack $ case instr of LoadIm r v -> tag 0 ++# encodeReg r ++# pack v -- Pad with zeros Add a b d -> tag 1 ++# encodeReg a ++# encodeReg b ++# encodeReg d ++# 0 Sub a b d -> tag 2 ++# encodeReg a ++# encodeReg b ++# encodeReg d ++# 0 Mul a b d -> tag 3 ++# encodeReg a ++# encodeReg b ++# encodeReg d ++# 0 Load v p -> tag 4 ++# encodeReg v ++# encodeReg p ++# 0 Store v p -> tag 5 ++# encodeReg v ++# encodeReg p ++# 0 Jmp p -> tag 6 ++# encodeReg p ++# 0 JmpZ z d -> tag 7 ++# encodeReg z ++# encodeReg d ++# 0 Out v -> tag 8 ++# encodeReg v ++# 0 Halt -> tag 9 ++# 0 where -- This is just for clarity, and to specify how many bits a tag should be. tag :: BitVector 4 -> BitVector 4 tag x = x -- We could have up to 16 regs (0 through 15), -- but we're only using 4 for now. encodeReg :: Register -> BitVector 4 encodeReg R1 = 1 encodeReg R2 = 2 encodeReg R3 = 3 encodeReg R4 = 4 decodeInstruction :: Word -> Instruction decodeInstruction ( Word val) = case tag of 0 -> LoadIm a v 1 -> Add a b c 2 -> Sub a b c 3 -> Mul a b c 4 -> Load a b 5 -> Store a b 6 -> Jmp a 7 -> JmpZ a b 8 -> Out a 9 -> Halt _ -> error "Undefined instruction" where tag = slice Nat.d63 Nat.d60 val a = decodeReg $ slice Nat.d59 Nat.d56 val b = decodeReg $ slice Nat.d55 Nat.d52 val c = decodeReg $ slice Nat.d51 Nat.d48 val v = unpack $ slice Nat.d55 Nat.d0 val decodeReg :: BitVector 4 -> Register decodeReg 1 = R1 decodeReg 2 = R2 decodeReg 3 = R3 decodeReg 4 = R4 decodeReg _ = error "Invalid register"

CPU Logic

Our entire CPU logic can be described by a function that takes the current CPU state/RAM contents and returns a new CPU state/RAM contents. In hardware, this corresponds to copying over the entire RAM every clock cycle. It can be done, but it's wasteful, so we're only going to do it in this first CPU.

cycle :: ( CPUState , RAM ) -> ( CPUState , RAM ) cycle ( CPUState activity registers, ram) = case activity of

Depending on the CPU's current state, we do different things. If the CPU is currently LoadingInstruction , we simply read the instruction from RAM and decode it. In future (more realistic) CPUs, this will happen over multiple cycles. For now, it happens in one cycle. After reading the instruction, we return a new state where the CPU is ExecutingInstruction . We also increment the program counter register pc by one.

LoadingInstruction -> ( CPUState activity' registers', ram) where loadedWord = readRAM ram (pc registers) activity' = ExecutingInstruction (decodeInstruction loadedWord) registers' = registers {pc = increment (pc registers)}

If the CPU is currently ExecutingInstruction , we inspect the instruction and perform the appropriate action.

ExecutingInstruction instr -> case instr of

LoadIm is very simple; we just expand the 56-bit immediate value to 64 bits and store it in the register.

LoadIm reg val -> ( CPUState LoadingInstruction registers', ram) where registers' = writeRegister registers reg (zeroExtend val)

Add , Sub , and Mul are all very similar:

Add a b d -> ( CPUState LoadingInstruction registers', ram) where result = readRegister registers a + readRegister registers b registers' = writeRegister registers d result Sub a b d -> ( CPUState LoadingInstruction registers', ram) where result = readRegister registers a - readRegister registers b registers' = writeRegister registers d result Mul a b d -> ( CPUState LoadingInstruction registers', ram) where result = readRegister registers a * readRegister registers b registers' = writeRegister registers d result

We don't have to actually implement integer addition, subtraction, and multiplication ourselves at the circuit level; these are pre-defined primitives in HDLs that hardware compilers know how to optimize aggressively.

For Load and Store , we will switch to the ReadingMemory / WritingMemory states. This isn't strictly necessary in our example hardware, as we could perform a load or store in the same cycle as ExecutingInstruction . However, I want to get us used to the idea of memory operations being slow and requiring special consideration.

Load valReg ptrReg -> ( CPUState ( ReadingMemory ptr valReg) registers, ram) where ptr = Ptr (readRegister registers ptrReg) Store valReg ptrReg -> ( CPUState ( WritingMemory ptr val) registers, ram) where ptr = Ptr (readRegister registers ptrReg) val = Word (readRegister registers valReg)

For Jmp , we just need to modify the program counter. For JmpZ , we'll need to modify our program counter depending on whether or not the specified register is zero. Then, we need to go to the LoadingInstruction state.

Jmp destReg -> ( CPUState LoadingInstruction registers', ram) where registers' = registers {pc = Ptr (readRegister registers destReg)} JmpZ zeroReg destReg -> ( CPUState LoadingInstruction registers', ram) where registers' = if readRegister registers zeroReg == 0 then registers {pc = Ptr (readRegister registers destReg)} else registers

For Out , we simply need to switch to the Outputting state.

Out reg -> ( CPUState ( Outputting output) registers, ram) where output = Output (readRegister registers reg)

For Halt , we switch to the Halted state.

Halt -> ( CPUState Halted registers, ram)

That covers all the instructions! Now we just need to handle a few more possible CPU states.

For ReadingMemory and WritingMemory , we simply perform the requested RAM operation, write the new value, and go back to LoadingInstruction .

ReadingMemory ptr reg -> ( CPUState LoadingInstruction registers', ram) where Word ramValue = readRAM ram ptr registers' = writeRegister registers reg ramValue WritingMemory ptr val -> ( CPUState LoadingInstruction registers, ram') where ram' = writeRAM ram ptr val

For Outputting , we simply stay in the Outputting state for a single cycle and then go back to LoadingInstruction . When we write the I/O hardware, we will actually output the value.

Outputting _ -> ( CPUState LoadingInstruction registers, ram)

For Halted , we just stay Halted forever.

Halted -> ( CPUState Halted registers, ram)

Now we'll write a couple functions to get information from the CPU state:

isHalted :: CPUState -> Bool isHalted ( CPUState Halted _) = True isHalted _ = False output :: CPUState -> Maybe Output output ( CPUState ( Outputting output) _) = Just output output _ = Nothing

Interlude: Registers

There are, in the context of digital circuitry, two kinds of circuit elements: combinational circuits and registers.

Combinational circuits are circuits which don't have any kind of memory. You put some values on their input bits, over a few nanoseconds electrical signals propagate through the transistors, and then there is some value held on the output bits. In other words, the circuit calculates a pure function of its input, with no internal state.

Registers are bits of hardware that hold some information for the duration of a clock cycle. At the beginning of the clock cycle, the register reads its input value, and a few nanoseconds later the value is held on the output of the register. This repeats every clock cycle. Registers form the basis of memory in digital circuits.

To build circuits that can remember the past, we combine pure functions (combinational circuits) with explicit state (registers). One of the reasons Haskell is so good at representing hardware is that it already requires and helps you to make this distinction.

In diagrams, we represent combinational circuits (pure functions) as boxes, like so:

f is the name of the function evaluated by the circuit, and the various arrows coming in and out of the box are the function's inputs and outputs.

We represent registers as rectangles with a triangle, like so:

The triangle is often connected to a clock signal, but in this series everything will use the same clock signal so we'll leave that implicit.

OK, now that we've covered a bit of how things are actually represented in hardware:

Hardware Structure

Now we're going to define how the CPU lives in hardware.

The output of our CPU is a stream of Bool s (for whether the CPU has halted) and Maybe Output s (for any outputs the CPU might emit). We get to pick the CPU's initial state and RAM contents.

cpuHardware :: CPUState -> RAM -> Signal ( Bool , Maybe Output ) cpuHardware initialCPUState initialRAM = outputSignal where

First, we're going to put the CPU state and RAM contents into a hardware register, which (as described above) is a hardware-level memory cell. CLaSH provides a register function which takes the initial register contents and the input signal to the register (which the register reads into itself at the start of every clock cycle), and returns the output signal of the register (which is just a copy of the register's contents).

systemState = register (initialCPUState, initialRAM) systemState'

In real life, RAM is entirely different from register memory; register memory is much faster, but also much more expensive and less space-efficient. Storing our "RAM" in a register is just a pedagogical shortcut for this first installment.

Every cycle, the register replaces the old systemState with systemState' , which is defined as the cycle function applied to the old systemState .

systemState' = fmap cycle systemState

That part might seem a bit confusing because it's self-referential. Self-referential Haskell code is how we make self-referential circuits, which is how you build hardware with memory. The output of the register is being run through an update function, and the output of that is loaded into the register at the beginning of every clock cycle. If s[t] is the state at cycle t , then

s[0] = (initialCPUState, initialRAM) s[1] = cycle s[0] s[2] = cycle s[1] ...

Now we have to take the state of the CPU, extract the relevant information from the state, and output that information.

getOutput :: ( CPUState , RAM ) -> ( Bool , Maybe Output ) getOutput (state, _) = (isHalted state, output state)

Every cycle, our output signal should contain the output data for the new state.

outputSignal = fmap getOutput systemState'

This is what the actual circuit will end up looking like:

Let's also define an initial CPU state with all registers (including pc ) set to zero:

defaultCPUState :: CPUState defaultCPUState = CPUState LoadingInstruction ( Registers 0 0 0 0 ( Ptr 0 ))

That's enough code for us to test our CPU in Haskell. Let's write some programs.

Programming the CPU

Let's first write a very simple program that just outputs 7, 8, 9.

simpleProgram :: Vec 7 Instruction simpleProgram = LoadIm R1 7 :> LoadIm R2 8 :> LoadIm R3 9 :> Out R1 :> Out R2 :> Out R3 :> Halt :> Nil

And let's compile it into memory:

simpleProgramMem :: Vec 64 Word simpleProgramMem = fmap encodeInstruction simpleProgram ++ repeat ( Word 0 )

We fill unused memory with a bunch of zeros.

Let's generate CPU hardware with this program pre-loaded:

simpleProgramCPU :: Signal ( Bool , Maybe Output ) simpleProgramCPU = cpuHardware defaultCPUState ( RAM simpleProgramMem)

Because CLaSH is a wrapper around plain old Haskell, we can test our entire CPU design without ever having to put it in hardware. Let's use the sample function to get a list of the first 20 outputs from our CPU, one output per clock cycle.

simpleProgramOutput :: [( Bool , Maybe Output )] simpleProgramOutput = take 20 $ sample simpleProgramCPU

Before we look at the output, let's take a moment to think about what we should expect.

The CPU starts out in LoadingInstruction , so it shouldn't output anything the first cycle. The second cycle, it executes the first LoadIm in the ExecutingInstruction state. Then, it goes back to LoadingInstruction . So each LoadIm takes one cycle to load and one cycle to execute. So we should first expect 5 cycles with no output, and then we're back to a LoadingInstruction .

Then, for each Out instruction, the CPU has to go through a LoadingInstruction , then an ExecutingInstruction , then an Outputting state. So for every Out , there should be two cycles with no output and one cycle with an output. So we should spend 9 cycles on Out s.

Then, for Halt , we have to go through LoadingInstruction , ExecutingInstruction , and then finally to Halt . So this should take a total of 3 cycles.

The total, then, is 17 cycles for this program to execute. On the 17th cycle, the halt bit should be True , and it should stay that way.

Indeed, if we type mapM_ print simpleProgramOutput at our interactive prompt, we get

(False,Nothing) (False,Nothing) (False,Nothing) (False,Nothing) (False,Nothing) (False,Nothing) (False,Nothing) (False,Just (Output 7)) (False,Nothing) (False,Nothing) (False,Just (Output 8)) (False,Nothing) (False,Nothing) (False,Just (Output 9)) (False,Nothing) (False,Nothing) (True,Nothing) (True,Nothing) (True,Nothing) (True,Nothing)

Which is exactly what we wanted!

Let's try a more complicated program, with a loop.

loopProgram :: Vec 9 Instruction loopProgram = LoadIm R1 1 :> -- Constant 1 LoadIm R2 5 :> -- Loop counter LoadIm R3 4 :> -- Jump destination ("Out R2") LoadIm R4 8 :> -- Jump destination ("Halt") Out R2 :> -- Output the current counter value JmpZ R2 R4 :> -- Halt if R2 == 0 Sub R2 R1 R2 :> -- Decrement R2 Jmp R3 :> -- Go to the start of the loop Halt :> Nil loopProgramMem :: Vec 64 Word loopProgramMem = fmap encodeInstruction loopProgram ++ repeat ( Word 0 ) loopProgramCPU :: Signal ( Bool , Maybe Output ) loopProgramCPU = cpuHardware defaultCPUState ( RAM loopProgramMem) -- Let's ignore boring outputs isBoring :: ( Bool , Maybe Output ) -> Bool isBoring ( False , Nothing ) = True isBoring _ = False loopProgramOutput :: [( Bool , Maybe Output )] loopProgramOutput = take 7 $ filter (not . isBoring) $ sample loopProgramCPU

And if we print out the output:

(False,Just (Output 5)) (False,Just (Output 4)) (False,Just (Output 3)) (False,Just (Output 2)) (False,Just (Output 1)) (False,Just (Output 0)) (True,Nothing)

Great! Just what we wanted.

And let's make a program that puts the first 20 fibonacci terms in RAM. We'll use R1 as a constant values register and R2 as a pointer register.

fibProgram :: Vec 27 Instruction fibProgram = LoadIm R1 0 -- Store the first 2 terms (0,1) in RAM :> LoadIm R2 0x20 :> Store R1 R2 :> LoadIm R1 1 :> LoadIm R2 0x21 :> Store R1 R2 :> LoadIm R3 0 -- Loop counter :> LoadIm R2 0x20 -- Start of loop. Load fibonacci array base address :> Add R2 R3 R2 -- Get the address of the current first term (R2 + R3) :> Load R4 R2 -- Load the first item into R4 :> LoadIm R1 1 :> Add R2 R1 R2 -- Get the address of the second item (R2 + R3 + 1) :> Load R1 R2 -- Load the second item into R1 :> Add R4 R1 R4 -- Add up the first and second items into R4 :> LoadIm R1 1 :> Add R2 R1 R2 -- Get the address of the new item (R2 + R3 + 2) :> Store R4 R2 -- Store the new item :> Out R4 -- Print the new item :> LoadIm R1 19 :> Sub R1 R3 R1 -- R1 = 19 - loop count :> LoadIm R2 haltAddr -- R2 = Halt address :> JmpZ R1 R2 -- Halt if R1 == 0 (i.e. if loop count is 19) :> LoadIm R1 1 :> Add R3 R1 R3 -- Increment loop counter :> LoadIm R2 loopStart :> Jmp R2 -- Go back to loop start :> Halt :> Nil where haltAddr = 26 loopStart = 7 fibProgramMem :: Vec 64 Word fibProgramMem = fmap encodeInstruction fibProgram ++ repeat ( Word 0 ) fibProgramCPU :: Signal ( Bool , Maybe Output ) fibProgramCPU = cpuHardware defaultCPUState ( RAM fibProgramMem) fibProgramOutput :: [( Bool , Maybe Output )] fibProgramOutput = take 21 $ filter (not . isBoring) $ sample fibProgramCPU

And indeed, we get

(False,Just (Output 1)) (False,Just (Output 2)) (False,Just (Output 3)) (False,Just (Output 5)) (False,Just (Output 8)) (False,Just (Output 13)) ... (False,Just (Output 6765)) (False,Just (Output 10946)) (True,Nothing)

Sweet!

Interfacing With Hardware

OK, now for the final step in today's tutorial: putting this thing in actual hardware.

This part is pretty simple. First, we want to take the Signal (Bool, Maybe Output) stream from our CPU, which has an ambiguous/arbitrary bit-level representation, and transform it into a stream of something that has an unambiguous bit-level representation. This will let us plug our CPU code into other hardware code, in the hardware language of our choice.

hardwareTranslate :: ( Bool , Maybe Output ) -> ( Bit , Bit , BitVector 64 ) hardwareTranslate (halted, output) = (haltedBit, outputActive, outputValue) where haltedBit = if halted then 1 else 0 (outputActive, outputValue) = case output of Nothing -> ( 0 , 0 ) Just ( Output val) -> ( 1 , pack val)

Now we can apply this function to our stream of CPU output values to get a stream of bit values. If we call this stream of bit values topEntity , CLaSH knows that we want to compile this to a hardware object.

topEntity :: Signal ( Bit , Bit , BitVector 64 ) topEntity = fmap hardwareTranslate fibProgramCPU

To compile the CPU, we just run clash --verilog CPU1.lhs .

This generates a bunch of .v files in ./verilog/CPU1 .

We use the following Verilog file (call it cpu1.v ) to run our CPU hardware:

`timescale 1ns/1ns module main(); // Toggle the reset line initial begin reset_reg = 1 ; reset_reg = #1 0 ; reset_reg = #2 1 ; end reg reset_reg; wire reset = reset_reg; // Clock line reg theClock = 0 ; assign clk = theClock; always begin #50 ; theClock = !theClock; end wire halt; wire output_valid; wire [ 63 : 0 ] output_data; CPU1_topEntity cpu(clk, reset, halt, output_valid, output_data); [email protected]( posedge clk) begin if (output_valid == 1 ) begin $display ( "0x%h" , output_data); end else begin $display ( "." ); end end [email protected]( posedge clk) begin if (halt == 1 ) $finish ; end endmodule

This prints the output data if there is any or a dot if there isn't any.

To compile the iverilog simulation, run

clash --verilog CPU1.lhs iverilog -o cpu -s main cpu1.v verilog/CPU1/*.v

And to run it, run

timeout 10 ./cpu

You should start seeing CPU output!

Up Next

In part 2, we're going to cover more realistic RAM behavior and CPU pipelining, which will bring us closer to modern processors.