Electrical Nerd + Digital Artist Zola 2025-12-29T00:00:00+00:00 https://samienr.com/tags/projects/atom.xml 2025-12-29T00:00:00+00:00 2025-12-29T00:00:00+00:00 Samien Rahman https://samienr.com/blog/designing-a-cpu-03/ <p>Last time, we finished off with a very barebones set of components for our RISC-V core. Now we can begin with the first half of most interesting part of this process: connecting the datapath and creating the control signals.</p> <p>Microarchitectures are typically divided into two parts: a datapath and a control unit. The datapath consists of structures that hold the architectural state of the machine (like those we made in Part 2 of these blogs). It also houses a bunch of combinational logic which is used to process that state information and create new state information for the next state. This is what we will be making in this blog entry.</p> <p>This is all driven by the control unit, which receives state information from the datapath, then tells the datapath what to do using control signals, such as write enables, mux selectors, and any other "decisions" our datapath logic has to make. We will figure out what control signals we need in Part 4 after creating the datapath.</p> <p>We will begin by putting together the components we made last time, in addition to making some smaller components that will be needed to make these connections. In the next part we will create a set of control signals and a control unit to assert appropriate signals for each instruction.</p> <h1 id="pipeline-registers">Pipeline Registers</h1> <p>Let's start by taking a look at the components we made in <a href="https://samienr.com/blog/designing-a-cpu-02/">Part 2</a>.</p> <figure> <img class=" " src="basicComponents.png" /> <figcaption>The components we made in Part 2: PC, ALU, instruction and data memory</figcaption> </figure> <p>Since this is a pipelined machine, before we wire everything up, we need to think about what stage we want each component to be used in. Each instruction will propagate through all five stages of the pipeline: instruction fetch (<code>IF</code>), instruction decode (<code>ID</code>), address generation/execute (<code>AGEX</code>), memory access (<code>M</code>), and writeback (<code>WB</code>). Since an instruction can only occupy one stage at a time, we need a way to keep track of data and control signals for each instruction as it traverses the pipeline stages. We will place registers between each stage that will store whatever information an instruction may need as it is processed. Now, whenever we want to place a component into the datapath, we need to consider what stage it would best belong in.</p> <p>We know that the instruction memory must be accessed using the address in the PC during <code>IF</code>, so we will place them there. The register file will need to be accessed in <code>ID</code> so that source registers are ready to be accessed by the <code>AGEX</code> stage. The data memory will obviously need to be accessed during the <code>M</code> stage.</p> <figure> <img class=" " src="pipelineRegs.png" /> <figcaption>Each of the aforementioned components closest to the pipeline registers they will access the most</figcaption> </figure> <p>Now we will go through each pipeline stage and add whatever components are needed to support every instruction in the RV32I instruction set.</p> <h1 id="fetch">Fetch</h1> <p>The fetch stage is mostly already mostly done. The PC simply requests the I-cache for whatever instruction is at the PC's address. The I-cache retrieves the instruction and latches it into the <code>IF/ID</code> register. Additionally, the PC must update each with each instruction. In most cases it is simply incremented by 4, but branch and jump instructions will cause the PC to take another value. For this reason, we need to mux in all its possible next values. The target addressses for branches and <code>jal</code> are computed the same way, so those can share a mux input, and <code>jalr</code> will use the ALU output, so that will also need its own mux input.</p> <p>Now we can update the PC, however the PC does <em>not</em> change every cycle. As we will discuss in the next blog, there are cases where pipeline stages may stall. When this happens, we must not update the PC, hence we need to note that we need a control signal to indicate whether or not the PC should be updated in a cycle.</p> <p>And now that I've mentioned stalling, we might as well include some abstract hardware for that too.</p> <figure> <img class=" " src="IF.png" /> <figcaption>Instruction fetch stage</figcaption> </figure> <h1 id="decode">Decode</h1> <h2 id="control-unit">Control Unit</h2> <p>The decode stage takes the instruction fetched from the previous stage and figures out what the rest of the datapath should do with the instruction. Part of this involves producing the appropriate control signals for the instruction. Thus, the control unit belongs in this stage. In our case, the control unit is really just a big ROM where each entry is the set of control signals for a particular type of instruction. Since we don't yet know which control signals are needed, we'll design the datapath components first, assuming the control unit will provide the necessary signals. We'll specify the actual control signal values once the datapath requirements are clear.</p> <h2 id="immediate-generator">Immediate Generator</h2> <p>Since the immediate bit derivations are different for each instruction type, the value generation will use separate logic for each type of instruction. Depending on the instruction type, we will then select which decoding scheme we will use for the current instruction. <em>"How will we choose?"</em> you may ask <em><small>(or not)</small></em>. <em>This,</em> is the first place we will need to use a control signal. The control unit will look at the instruction type and determine what the appropriate selector bits for the immediate value mux should be. The correct value will come out of the mux and be latched into the <code>ID/AGEX</code> register.</p> <p>As for the implementation, it's just a matter of checking the opcode and then bit swizzling everything together, then sign extending:</p> <table><thead><tr><th>Instruction Type</th><th>Expression</th></tr></thead><tbody> <tr><td>I-type</td><td><code>{ {20{inst[31]}}, inst[31:20] }</code></td></tr> <tr><td>S-type</td><td><code>{ {20{inst[31]}}, inst[31:25], inst[11:7] }</code></td></tr> <tr><td>B-type</td><td><code>{ {19{inst[31]}}, inst[31], inst[7], inst[30:25], inst[11:8], 1'b0 }</code></td></tr> <tr><td>U-type</td><td><code>{ inst[31:12], 12'h000 }</code></td></tr> <tr><td>J-type</td><td><code>{ {11{inst[31]}}, inst[31], inst[19:12], inst[20], inst[30:21], 1'b0 }</code></td></tr> </tbody></table> <h2 id="register-file">Register File</h2> <p>Since RISC-V formats all its instruction types in a way such that the addresses of the source and destination registers are always in the same bit fields, pulling data out of the register file is trivial. To get our source registers, we simply need to get <code>IR[19:5]</code> for <code>rs1</code> and <code>IR[24:20]</code> for <code>rs2</code>. By the end of the clock cycle, these registers should be fetched and latched in for the <code>AGEX</code> stage. As for the destination register, whatever instruction is currently in the decode stage is not going to be ready to write back results just yet. In fact, the instructions that are ready to write back results will be those in the <code>WB</code> stage. Because of this, we're not going to connect <code>we</code> or any of the <code>rd</code> inputs quite yet. We'll come back to this later once we hit a stage where instructions are ready to write back their results.</p> <figure> <img class=" " src="ID.png" /> <figcaption>Instruction decode stage</figcaption> </figure> <h1 id="address-generation-execute">Address Generation/Execute</h1> <p>Like the name suggests, this stage does a few things, including:</p> <ol> <li>computing results for arithemic and logical operations</li> <li>generating target addresses for memory accesses and branch/jump targets</li> <li>producing conditional flags</li> </ol> <h2 id="execution">Execution</h2> <p>In Part 2, we discussed everything the ALU does. All of that happens here. All we have to do is determine what the ALU's operands are and wire it up. Most instructions will simply involve using two source registers. In these cases, <code>ALU_A</code> and <code>ALU_B</code> will be <code>rs1</code> and <code>rs2</code>, respectfully.<br /> However, that is not all. I and U-type instructions use immediate values instead of <code>rs2</code>, so that will need to be muxed. Additionally, the <code>auipc</code> instruction uses the PC instead of <code>rs1</code>, so that will also need to be muxed.</p> <h2 id="address-generation">Address Generation</h2> <p>All address generation comes from adding the PC with an offset which comes from the instruction's given immediate value. Since our immediate values were decoded and generated in the <code>ID</code> phase, they are ready to use in the <code>AGEX</code> stage. We can trivially pull the immediate values values from the <code>ID/AGEX</code> registers and then add that to the PC to get the correct PC offset. This is the target address for branches, jumps, and memory loads/stores.</p> <p>The <code>jalr</code> instruction is unique in that its target address comes from adding an immediate value to a source register, meaning its address generation must come from the ALU if we don't want to add more hardware. Additionally, RV32I requires that addresses generated by the <code>jalr</code> instruction are half-word aligned, so the last bit must be 0. This is due to maintaining compatibility with RV32C-capable machines.</p> <h2 id="condition-codes-flags">Condition Codes/Flags</h2> <p>To determine whether or not a branch should be taken, <code>rs1</code> and <code>rs2</code> are compared according to what we mentioned in Part 2. Recall that when we made the ALU, the primary output was the result of the arithmetic or logical operation. But the secondary outputs were the <code>zero</code>, <code>lt</code> and <code>ltU</code> signals. We will use these as discussed in Part 2, along with another control signal to generate the PCMUX signal used in the <code>IF</code> stage. The reason we need another signal is because of the jump instructions. Since they are unconditional, we need a way to change our address no matter what.</p> <h2 id="control-hazard">Control Hazard</h2> <p>Because it takes until the <code>AGEX</code> stage to determine what the next PC should be, this introduces what is called a hazard: What do we do with the two instructions fetched immediately after a jump or branch? We need a way to tell our machine to ignore those instructions in case the wrong instructions were fetched. This is a control hazard and will be handled later in Part 4 after we have a mostly complete control unit. This is because we want to have the entire big picture in mind when managing hazards.</p> <figure> <img class=" " src="AGEX.png" /> <figcaption>Address generate/execute stage</figcaption> </figure> <h1 id="memory-access">Memory Access</h1> <p>The memory stage of the pipeline is quite simple in terms of hardware with our level of abstraction. We only need to supply the data memory unit with an address and some control signals for write accesses. If the current instruction is a load instruction, then the data of whatever is at the supplied address must be latched for the <code>WB</code> stage.</p> <p>We'll also need a control signal to ensure that accesses are processed in an appropriate manner for the right data size for each instruction.</p> <p>Additionally, since memory can take several cycles to be ready, we will need to ensure that we know whether or not we are ready to move the instruction to the next stage yet or if we need to wait a little longer for the memory to be ready.</p> <figure> <img class=" " src="M.png" /> <figcaption>Memory access stage</figcaption> </figure> <h1 id="writeback">Writeback</h1> <p>This is arguably the simplest pipeline stage, as all it does is write whatever needs to be written into whatever register needs to be changed, given that the instruction does need to write something to a register.</p> <p>Many instructions will compute something with the ALU during <code>AGEX</code> and then write that result into <code>rd</code>, whose address is given by the instruction. Load instructions will use the retrieved data from <code>M</code>, and jump instructions will store the return linkage into <code>rd</code>.</p> <figure> <img class=" " src="WB.png" /> <figcaption>Writeback stage</figcaption> </figure> <h1 id="putting-it-all-together">Putting It All Together</h1> <p>Now that we have our individual stages, it is time to connect them all! We're now halfway done with the CPU. All that's left now is determining control signals and creating the control unit. After that, we need to consider hazards and then test the design by hand-tracing all the RV32I instructions as a final verification step before we begin the implementation for an FPGA.</p> <figure> <p><img src="https://samienr.com/blog/designing-a-cpu-03/datapath.png#full-bleed" alt="" loading="lazy" decoding="async" /></p> <figcaption>Our (mostly) complete pipeline datapath</figcaption> </figure> 2025-12-19T00:00:00+00:00 2025-12-19T00:00:00+00:00 Samien Rahman https://samienr.com/blog/designing-a-cpu-02/ <h1 id="arithmetic-logic-unit-alu">Arithmetic Logic Unit (ALU)</h1> <p>After skimming through the RV32I instruction set, I figured I could start with the arithmetic logic unit (ALU). The ALU is where most actual computations happen. Its composition depends on what operations it needs to perform. For RV32I, these are the operations I will need to implement for a functional ALU:</p> <table><thead><tr><th>Instruction</th><th>ALU Unit Needed</th></tr></thead><tbody> <tr><td><code>add</code>, <code>addi</code></td><td>Adder</td></tr> <tr><td><code>sub</code>, <code>slt</code>, <code>sltu</code></td><td>Subtractor</td></tr> <tr><td><code>slli</code>, <code>srli</code>, <code>srai</code>, <code>sll</code>, <code>sra</code>, <code>srl</code></td><td>Shifter</td></tr> <tr><td><code>and</code>, <code>or</code>, <code>xor</code>, <code>andi</code>, <code>ori</code>, <code>xori</code></td><td>Primitive logic gates</td></tr> </tbody></table> <p>Our design will simply have circuitry to compute all these operations and then multiplex out whatever an <code>ALU_Op</code> control signal requests.</p> <p>I'm aware that there are some other instructions that do math, such as <code>auipc</code> and <code>lui</code>. These operations will use their own dedicated hardware outside of the ALU.</p> <h2 id="condition-codes-flags">Condition Codes/Flags</h2> <p>In addition to the operations, our machine also needs to generate condition flags. RV32I doesn't really define how we will handle whether branches are taken or not, so how we approach this is up to us. The simplest approach I found was only checking for three conditions:</p> <ol> <li>Is our result zero?</li> <li>Is A &lt; B? (unsigned)</li> <li>Is A &lt; B? (signed)</li> </ol> <p>We can easily use the results of the subtractor for these signals. Every type of branch instruction we will need to consider can be resolved using these three conditions.</p> <table><thead><tr><th>Instruction</th><th>Logical Condition</th><th>ALU Signal</th></tr></thead><tbody> <tr><td>beq</td><td>A == B</td><td>Zero</td></tr> <tr><td>bne</td><td>A != B</td><td>NOT Zero</td></tr> <tr><td>bltu</td><td>A &lt; B (unsigned)</td><td>A &lt; B (unsigned)</td></tr> <tr><td>bgeu</td><td>A &gt;= B (unsigned)</td><td>NOT A &lt; B (unsigned)</td></tr> <tr><td>blt</td><td>A &lt; B (signed)</td><td>A &lt; B (signed)</td></tr> <tr><td>bge</td><td>A &gt;= B (signed)</td><td>NOT A &lt; B (signed)</td></tr> </tbody></table> <p>The <code>zero</code> condition will simply check if A and B are equal to each other.<br /> The less than (unsigned) condition <code>ltU</code> will be computed by subtracting <code>A - B</code> and taking the complement of the subtractor's borrow bit.<br /> The less than (signed) condition <code>lt</code> will use the same subtractor and result. Its value will come from the <code>XOR</code> of the subtractor's borrow bit and another signal that indicates whether or not the subtractor had overflow.</p> <h2 id="alu-code">ALU Code</h2> <pre data-lang="verilog" style="background-color:#212733;color:#ccc9c2;" class="language-verilog "><code class="language-verilog" data-lang="verilog"><span style="color:#ffa759;">module </span><span style="color:#73d0ff;">ALU</span><span>( </span><span style="font-style:italic;color:#5ccfe6;"> input</span><span> [</span><span style="color:#ffcc66;">31</span><span style="color:#f29e74;">:</span><span style="color:#ffcc66;">0</span><span>] </span><span style="color:#ffcc66;">A</span><span>, </span><span style="font-style:italic;color:#5ccfe6;"> input</span><span> [</span><span style="color:#ffcc66;">31</span><span style="color:#f29e74;">:</span><span style="color:#ffcc66;">0</span><span>] </span><span style="color:#ffcc66;">B</span><span>, </span><span style="font-style:italic;color:#5ccfe6;"> input</span><span> [</span><span style="color:#ffcc66;">3</span><span style="color:#f29e74;">:</span><span style="color:#ffcc66;">0</span><span>] ALU_Op, </span><span> </span><span style="font-style:italic;color:#5ccfe6;">output </span><span style="color:#ffa759;">reg</span><span> [</span><span style="color:#ffcc66;">31</span><span style="color:#f29e74;">:</span><span style="color:#ffcc66;">0</span><span>] Result, </span><span style="font-style:italic;color:#5ccfe6;"> output</span><span> zero, lt, ltU </span><span> ); </span><span> </span><span style="color:#ffa759;">wire</span><span> [</span><span style="color:#ffcc66;">32</span><span style="color:#f29e74;">:</span><span style="color:#ffcc66;">0</span><span>] sub_full </span><span style="color:#f29e74;">= {</span><span style="color:#ffcc66;">1&#39;b0</span><span>, </span><span style="color:#ffcc66;">A</span><span style="color:#f29e74;">} - {</span><span style="color:#ffcc66;">1&#39;b0</span><span>, </span><span style="color:#ffcc66;">B</span><span style="color:#f29e74;">}</span><span>; </span><span style="color:#ffa759;">wire</span><span> sub_overflow </span><span style="color:#f29e74;">=</span><span> (</span><span style="color:#ffcc66;">A</span><span>[</span><span style="color:#ffcc66;">31</span><span>] </span><span style="color:#f29e74;">^ </span><span style="color:#ffcc66;">B</span><span>[</span><span style="color:#ffcc66;">31</span><span>]) </span><span style="color:#f29e74;">&amp;</span><span> (sub_full[</span><span style="color:#ffcc66;">31</span><span>] </span><span style="color:#f29e74;">^ </span><span style="color:#ffcc66;">A</span><span>[</span><span style="color:#ffcc66;">31</span><span>]); </span><span> </span><span style="color:#ffa759;">assign</span><span> zero </span><span style="color:#f29e74;">= </span><span style="color:#ffcc66;">A </span><span style="color:#f29e74;">== </span><span style="color:#ffcc66;">B</span><span>; </span><span style="color:#ffa759;">assign</span><span> lt </span><span style="color:#f29e74;">=</span><span> sub_full[</span><span style="color:#ffcc66;">31</span><span>] </span><span style="color:#f29e74;">^</span><span> sub_overflow; </span><span style="color:#ffa759;">assign</span><span> ltU </span><span style="color:#f29e74;">= ~</span><span>sub_full[</span><span style="color:#ffcc66;">32</span><span>]; </span><span> </span><span style="color:#ffa759;">always </span><span style="color:#f29e74;">@</span><span>(</span><span style="color:#f29e74;">*</span><span>) </span><span style="color:#ffa759;">begin </span><span>Result </span><span style="color:#f29e74;">= </span><span style="color:#ffcc66;">32&#39;b0</span><span>; </span><span> </span><span style="color:#ffa759;">case</span><span> (ALU_Op) </span><span> </span><span style="color:#ffcc66;">`ALU_ADD</span><span style="color:#f29e74;">:</span><span> Result </span><span style="color:#f29e74;">= </span><span style="color:#ffcc66;">A </span><span style="color:#f29e74;">+ </span><span style="color:#ffcc66;">B</span><span>; </span><span> </span><span style="color:#ffcc66;">`ALU_SUB</span><span style="color:#f29e74;">:</span><span> Result </span><span style="color:#f29e74;">=</span><span> sub_full[</span><span style="color:#ffcc66;">31</span><span style="color:#f29e74;">:</span><span style="color:#ffcc66;">0</span><span>]; </span><span> </span><span style="color:#ffcc66;">`ALU_SHF_L</span><span style="color:#f29e74;">:</span><span> Result </span><span style="color:#f29e74;">= </span><span style="color:#ffcc66;">A </span><span style="color:#f29e74;">&lt;&lt; </span><span style="color:#ffcc66;">B</span><span>[</span><span style="color:#ffcc66;">4</span><span style="color:#f29e74;">:</span><span style="color:#ffcc66;">0</span><span>]; </span><span> </span><span style="color:#ffcc66;">`ALU_SHF_R_L</span><span style="color:#f29e74;">:</span><span> Result </span><span style="color:#f29e74;">= </span><span style="color:#ffcc66;">A </span><span style="color:#f29e74;">&gt;&gt; </span><span style="color:#ffcc66;">B</span><span>[</span><span style="color:#ffcc66;">4</span><span style="color:#f29e74;">:</span><span style="color:#ffcc66;">0</span><span>]; </span><span> </span><span style="color:#ffcc66;">`ALU_SHF_R_A</span><span style="color:#f29e74;">:</span><span> Result </span><span style="color:#f29e74;">= </span><span style="color:#f28779;">$signed</span><span>(</span><span style="color:#ffcc66;">A</span><span>) </span><span style="color:#f29e74;">&gt;&gt;&gt; </span><span style="color:#ffcc66;">B</span><span>[</span><span style="color:#ffcc66;">4</span><span style="color:#f29e74;">:</span><span style="color:#ffcc66;">0</span><span>]; </span><span> </span><span style="color:#ffcc66;">`ALU_AND</span><span style="color:#f29e74;">:</span><span> Result </span><span style="color:#f29e74;">= </span><span style="color:#ffcc66;">A </span><span style="color:#f29e74;">&amp; </span><span style="color:#ffcc66;">B</span><span>; </span><span> </span><span style="color:#ffcc66;">`ALU_OR</span><span style="color:#f29e74;">:</span><span> Result </span><span style="color:#f29e74;">= </span><span style="color:#ffcc66;">A </span><span style="color:#f29e74;">| </span><span style="color:#ffcc66;">B</span><span>; </span><span> </span><span style="color:#ffcc66;">`ALU_XOR</span><span style="color:#f29e74;">:</span><span> Result </span><span style="color:#f29e74;">= </span><span style="color:#ffcc66;">A </span><span style="color:#f29e74;">^ </span><span style="color:#ffcc66;">B</span><span>; </span><span> </span><span style="color:#ffcc66;">`ALU_PASSB</span><span style="color:#f29e74;">:</span><span> Result </span><span style="color:#f29e74;">= </span><span style="color:#ffcc66;">B</span><span>; </span><span> </span><span style="color:#ffcc66;">`ALU_SLT</span><span style="color:#f29e74;">:</span><span> Result </span><span style="color:#f29e74;">= {{</span><span style="color:#ffcc66;">31</span><span style="color:#f29e74;">{</span><span style="color:#ffcc66;">1&#39;b0</span><span style="color:#f29e74;">}}</span><span>, lt</span><span style="color:#f29e74;">}</span><span>; </span><span> </span><span style="color:#ffcc66;">`ALU_SLTU</span><span style="color:#f29e74;">:</span><span> Result </span><span style="color:#f29e74;">= {{</span><span style="color:#ffcc66;">31</span><span style="color:#f29e74;">{</span><span style="color:#ffcc66;">1&#39;b0</span><span style="color:#f29e74;">}}</span><span>, ltU</span><span style="color:#f29e74;">}</span><span>; </span><span> </span><span style="color:#ffa759;">default</span><span style="color:#f29e74;">:</span><span> Result </span><span style="color:#f29e74;">= </span><span style="color:#ffcc66;">A</span><span>; </span><span> </span><span style="color:#ffa759;">endcase </span><span style="color:#ffa759;">end </span><span style="color:#ffa759;">endmodule </span></code></pre> <h1 id="register-file">Register File</h1> <p>This is one of the most trivial yet most important components to make. Since we won't be doing anything superscalar or out-of-order just yet, we can get away with writing a very simple register file with just two read ports and one write port. Our ISA tells us that we have 32 registers with 32 bits each. Since reading doesn't change state, we can make that part combinational and save some time. However, since writing does change state, it must be synchronized, so changes will only be made on rising clock edges. Other than that, the only thing we need to keep in mind is that the x0 register (address 0b00000) is always 0, and writing to it makes no changes.</p> <p><strong>EDIT:</strong> Looks like I missed something here. Since this machine is going to be pipelined, we need to account for the case where one register is being written by one instruction, but is simultaneously being read by a future instruction in an earlier phase of the pipeline. In this case, the value that is being written must be forwarded to the next instruction, <em>not</em> the value that was there before. To fix this, all we need is the ability to directly output what is being written if the destination register happens to be one of the source registers.</p> <h2 id="register-file-code">Register File Code</h2> <pre data-lang="verilog" style="background-color:#212733;color:#ccc9c2;" class="language-verilog "><code class="language-verilog" data-lang="verilog"><span style="color:#ffa759;">module </span><span style="color:#73d0ff;">RegFile</span><span>( </span><span style="font-style:italic;color:#5ccfe6;"> input</span><span> clk, </span><span style="font-style:italic;color:#5ccfe6;"> input</span><span> [</span><span style="color:#ffcc66;">4</span><span style="color:#f29e74;">:</span><span style="color:#ffcc66;">0</span><span>] rs1, </span><span style="font-style:italic;color:#5ccfe6;"> input</span><span> [</span><span style="color:#ffcc66;">4</span><span style="color:#f29e74;">:</span><span style="color:#ffcc66;">0</span><span>] rs2, </span><span style="font-style:italic;color:#5ccfe6;"> input</span><span> we, </span><span style="font-style:italic;color:#5ccfe6;"> input</span><span> [</span><span style="color:#ffcc66;">4</span><span style="color:#f29e74;">:</span><span style="color:#ffcc66;">0</span><span>] wr_addr, </span><span style="font-style:italic;color:#5ccfe6;"> input</span><span> [</span><span style="color:#ffcc66;">31</span><span style="color:#f29e74;">:</span><span style="color:#ffcc66;">0</span><span>] wr_data, </span><span style="font-style:italic;color:#5ccfe6;"> output</span><span> [</span><span style="color:#ffcc66;">31</span><span style="color:#f29e74;">:</span><span style="color:#ffcc66;">0</span><span>] rd1, </span><span style="font-style:italic;color:#5ccfe6;"> output</span><span> [</span><span style="color:#ffcc66;">31</span><span style="color:#f29e74;">:</span><span style="color:#ffcc66;">0</span><span>] rd2 </span><span> ); </span><span> </span><span style="color:#ffa759;"> reg</span><span> [</span><span style="color:#ffcc66;">31</span><span style="color:#f29e74;">:</span><span style="color:#ffcc66;">0</span><span>] registers[</span><span style="color:#ffcc66;">31</span><span style="color:#f29e74;">:</span><span style="color:#ffcc66;">0</span><span>]; </span><span> </span><span> </span><span style="color:#ffa759;">always </span><span style="color:#f29e74;">@</span><span>(</span><span style="color:#ffa759;">posedge</span><span> clk) </span><span> </span><span style="color:#ffa759;">if</span><span> (we </span><span style="color:#f29e74;">&amp;&amp;</span><span> wr_addr </span><span style="color:#f29e74;">!= </span><span style="color:#ffcc66;">5&#39;b0</span><span>) </span><span> registers[wr_addr] </span><span style="color:#f29e74;">&lt;=</span><span> wr_data; </span><span> </span><span> </span><span style="color:#ffa759;">assign</span><span> rd1 </span><span style="color:#f29e74;">=</span><span> (rs1 </span><span style="color:#f29e74;">== </span><span style="color:#ffcc66;">0</span><span>) </span><span style="color:#f29e74;">? </span><span style="color:#ffcc66;">32&#39;b0 </span><span style="color:#f29e74;">: </span><span style="font-style:italic;color:#5c6773;">// read x0 </span><span> (rs1 </span><span style="color:#f29e74;">==</span><span> wr_addr </span><span style="color:#f29e74;">&amp;&amp;</span><span> we) </span><span style="color:#f29e74;">?</span><span> wr_data </span><span style="color:#f29e74;">: </span><span style="font-style:italic;color:#5c6773;">// bypass </span><span> registers[rs1]; </span><span style="font-style:italic;color:#5c6773;">// normal read </span><span> </span><span> </span><span style="color:#ffa759;">assign</span><span> rd2 </span><span style="color:#f29e74;">=</span><span> (rs2 </span><span style="color:#f29e74;">== </span><span style="color:#ffcc66;">0</span><span>) </span><span style="color:#f29e74;">? </span><span style="color:#ffcc66;">32&#39;b0 </span><span style="color:#f29e74;">: </span><span> (rs2 </span><span style="color:#f29e74;">==</span><span> wr_addr </span><span style="color:#f29e74;">&amp;&amp;</span><span> we) </span><span style="color:#f29e74;">?</span><span> wr_data </span><span style="color:#f29e74;">: </span><span> registers[rs2]; </span><span style="color:#ffa759;">endmodule </span></code></pre> <h1 id="program-counter-pc">Program Counter (PC)</h1> <p>Even more trivial than the register file is the PC. The PC is a simple 32-bit register that can be updated every cycle. In real hardware, this would be driven by some reset logic or a boot ROM.</p> <h2 id="pc-code">PC Code</h2> <pre data-lang="verilog" style="background-color:#212733;color:#ccc9c2;" class="language-verilog "><code class="language-verilog" data-lang="verilog"><span style="color:#ffa759;">module </span><span style="color:#73d0ff;">PC</span><span>( </span><span style="font-style:italic;color:#5ccfe6;"> input</span><span> clk, </span><span style="font-style:italic;color:#5ccfe6;"> input</span><span> we, </span><span style="font-style:italic;color:#5ccfe6;"> input</span><span> [</span><span style="color:#ffcc66;">31</span><span style="color:#f29e74;">:</span><span style="color:#ffcc66;">0</span><span>] in, </span><span style="font-style:italic;color:#5ccfe6;"> output</span><span> [</span><span style="color:#ffcc66;">31</span><span style="color:#f29e74;">:</span><span style="color:#ffcc66;">0</span><span>] out </span><span> ); </span><span> </span><span style="color:#ffa759;"> reg</span><span> [</span><span style="color:#ffcc66;">31</span><span style="color:#f29e74;">:</span><span style="color:#ffcc66;">0</span><span>] counter; </span><span> </span><span style="color:#ffa759;">initial</span><span> counter </span><span style="color:#f29e74;">= </span><span style="color:#ffcc66;">32&#39;h8000_0000</span><span>; </span><span> </span><span style="color:#ffa759;">assign</span><span> out </span><span style="color:#f29e74;">=</span><span> counter; </span><span> </span><span style="color:#ffa759;">always </span><span style="color:#f29e74;">@</span><span>(</span><span style="color:#ffa759;">posedge</span><span> clk) </span><span> </span><span style="color:#ffa759;">if</span><span> (we) counter </span><span style="color:#f29e74;">&lt;=</span><span> in; </span><span> </span><span style="color:#ffa759;">endmodule </span></code></pre> <h1 id="memory">Memory</h1> <p>Even though RISC-V architecturally has instruction and data memory unified, I'm going to keep instructions and data separate in hardware as it makes pipelining much less of a headache. They're usually cached separately in most machines anyways.</p> <h2 id="instructions">Instructions</h2> <p>We will make the instruction memory behave like a synchronous ROM. We'll also ensure that it is only word addressable.</p> <pre data-lang="verilog" style="background-color:#212733;color:#ccc9c2;" class="language-verilog "><code class="language-verilog" data-lang="verilog"><span style="font-style:italic;color:#5c6773;">// TODO: Add simulated delay </span><span> </span><span style="color:#ffa759;">module </span><span style="color:#73d0ff;">InstructionMemory</span><span>( </span><span style="font-style:italic;color:#5ccfe6;"> input</span><span> clk, </span><span style="font-style:italic;color:#5ccfe6;"> input</span><span> [</span><span style="color:#ffcc66;">31</span><span style="color:#f29e74;">:</span><span style="color:#ffcc66;">0</span><span>] addr, </span><span> </span><span style="font-style:italic;color:#5ccfe6;">output </span><span style="color:#ffa759;">reg</span><span> [</span><span style="color:#ffcc66;">31</span><span style="color:#f29e74;">:</span><span style="color:#ffcc66;">0</span><span>] instruction </span><span> ); </span><span style="color:#ffa759;"> reg</span><span> [</span><span style="color:#ffcc66;">31</span><span style="color:#f29e74;">:</span><span style="color:#ffcc66;">0</span><span>] mem [</span><span style="color:#ffcc66;">0</span><span style="color:#f29e74;">:</span><span style="color:#ffcc66;">1023</span><span>]; </span><span style="font-style:italic;color:#5c6773;">// 4KB Instruction Memory (1024 words) </span><span style="font-style:italic;color:#5c6773;">// TODO: load test program </span><span style="font-style:italic;color:#5c6773;">// initial $readmemh(&quot;program.hex&quot;, mem); </span><span> </span><span> </span><span style="color:#ffa759;">always </span><span style="color:#f29e74;">@</span><span>(</span><span style="color:#ffa759;">posedge</span><span> clk) </span><span> </span><span style="font-style:italic;color:#5c6773;">// chop off last two bits to ensure word aligned </span><span> instruction </span><span style="color:#f29e74;">&lt;=</span><span> mem[addr[</span><span style="color:#ffcc66;">11</span><span style="color:#f29e74;">:</span><span style="color:#ffcc66;">2</span><span>]]; </span><span> </span><span style="color:#ffa759;">endmodule </span></code></pre> <h2 id="data">Data</h2> <p>Data memory is a little more complicated as we need to be able to operate on bytes, halfwords, and words for stores. I'm just going to model this internally as an array of 8-bit registers. The input and output will be in terms of words, and a <code>byte_en</code> signal will determine how many bytes are actually going into memory.</p> <pre data-lang="verilog" style="background-color:#212733;color:#ccc9c2;" class="language-verilog "><code class="language-verilog" data-lang="verilog"><span style="font-style:italic;color:#5c6773;">// word aligned accesses only from core&#39;s POV, internally byte addresable </span><span style="color:#ffa759;">module </span><span style="color:#73d0ff;">DMem</span><span>( </span><span style="font-style:italic;color:#5ccfe6;"> input</span><span> clk, </span><span style="font-style:italic;color:#5ccfe6;"> input</span><span> we, </span><span style="font-style:italic;color:#5ccfe6;"> input</span><span> [</span><span style="color:#ffcc66;">3</span><span style="color:#f29e74;">:</span><span style="color:#ffcc66;">0</span><span>] byte_en, </span><span style="font-style:italic;color:#5ccfe6;"> input</span><span> [</span><span style="color:#ffcc66;">31</span><span style="color:#f29e74;">:</span><span style="color:#ffcc66;">0</span><span>] addr, </span><span style="font-style:italic;color:#5ccfe6;"> input</span><span> [</span><span style="color:#ffcc66;">31</span><span style="color:#f29e74;">:</span><span style="color:#ffcc66;">0</span><span>] din, </span><span> </span><span style="font-style:italic;color:#5ccfe6;">output </span><span style="color:#ffa759;">reg</span><span> [</span><span style="color:#ffcc66;">31</span><span style="color:#f29e74;">:</span><span style="color:#ffcc66;">0</span><span>] dout, </span><span style="font-style:italic;color:#5ccfe6;"> output</span><span> ready </span><span> ); </span><span> </span><span> </span><span style="color:#ffa759;">assign</span><span> ready </span><span style="color:#f29e74;">= </span><span style="color:#ffcc66;">1&#39;b1</span><span>; </span><span style="font-style:italic;color:#5c6773;">// TODO: simulate delay </span><span> </span><span style="color:#ffa759;"> reg</span><span> [</span><span style="color:#ffcc66;">7</span><span style="color:#f29e74;">:</span><span style="color:#ffcc66;">0</span><span>] mem[</span><span style="color:#ffcc66;">0</span><span style="color:#f29e74;">:</span><span style="color:#ffcc66;">4095</span><span>]; </span><span style="font-style:italic;color:#5c6773;">// 4KB addressable </span><span> </span><span> </span><span style="color:#ffa759;">always </span><span style="color:#f29e74;">@</span><span>(</span><span style="color:#ffa759;">posedge</span><span> clk) </span><span style="color:#ffa759;">begin </span><span> dout </span><span style="color:#f29e74;">&lt;= {</span><span>mem[addr[</span><span style="color:#ffcc66;">11</span><span style="color:#f29e74;">:</span><span style="color:#ffcc66;">0</span><span>] </span><span style="color:#f29e74;">+ </span><span style="color:#ffcc66;">3</span><span>], </span><span> mem[addr[</span><span style="color:#ffcc66;">11</span><span style="color:#f29e74;">:</span><span style="color:#ffcc66;">0</span><span>] </span><span style="color:#f29e74;">+ </span><span style="color:#ffcc66;">2</span><span>], </span><span> mem[addr[</span><span style="color:#ffcc66;">11</span><span style="color:#f29e74;">:</span><span style="color:#ffcc66;">0</span><span>] </span><span style="color:#f29e74;">+ </span><span style="color:#ffcc66;">1</span><span>], </span><span> mem[addr[</span><span style="color:#ffcc66;">11</span><span style="color:#f29e74;">:</span><span style="color:#ffcc66;">0</span><span>]]</span><span style="color:#f29e74;">}</span><span>; </span><span> </span><span style="color:#ffa759;">if</span><span> (we) </span><span style="color:#ffa759;">begin </span><span> </span><span style="color:#ffa759;">if</span><span> (byte_en[</span><span style="color:#ffcc66;">0</span><span>]) mem[addr[</span><span style="color:#ffcc66;">11</span><span style="color:#f29e74;">:</span><span style="color:#ffcc66;">0</span><span>]] </span><span style="color:#f29e74;">&lt;=</span><span> din[</span><span style="color:#ffcc66;">7</span><span style="color:#f29e74;">:</span><span style="color:#ffcc66;">0</span><span>]; </span><span> </span><span style="color:#ffa759;">if</span><span> (byte_en[</span><span style="color:#ffcc66;">1</span><span>]) mem[addr[</span><span style="color:#ffcc66;">11</span><span style="color:#f29e74;">:</span><span style="color:#ffcc66;">0</span><span>] </span><span style="color:#f29e74;">+ </span><span style="color:#ffcc66;">1</span><span>] </span><span style="color:#f29e74;">&lt;=</span><span> din[</span><span style="color:#ffcc66;">15</span><span style="color:#f29e74;">:</span><span style="color:#ffcc66;">8</span><span>]; </span><span> </span><span style="color:#ffa759;">if</span><span> (byte_en[</span><span style="color:#ffcc66;">2</span><span>]) mem[addr[</span><span style="color:#ffcc66;">11</span><span style="color:#f29e74;">:</span><span style="color:#ffcc66;">0</span><span>] </span><span style="color:#f29e74;">+ </span><span style="color:#ffcc66;">2</span><span>] </span><span style="color:#f29e74;">&lt;=</span><span> din[</span><span style="color:#ffcc66;">23</span><span style="color:#f29e74;">:</span><span style="color:#ffcc66;">16</span><span>]; </span><span> </span><span style="color:#ffa759;">if</span><span> (byte_en[</span><span style="color:#ffcc66;">3</span><span>]) mem[addr[</span><span style="color:#ffcc66;">11</span><span style="color:#f29e74;">:</span><span style="color:#ffcc66;">0</span><span>] </span><span style="color:#f29e74;">+ </span><span style="color:#ffcc66;">3</span><span>] </span><span style="color:#f29e74;">&lt;=</span><span> din[</span><span style="color:#ffcc66;">31</span><span style="color:#f29e74;">:</span><span style="color:#ffcc66;">24</span><span>]; </span><span> </span><span style="color:#ffa759;">end </span><span> </span><span style="color:#ffa759;">end </span><span> </span><span style="color:#ffa759;">endmodule </span></code></pre> <h1 id="what-s-next">What's Next?</h1> <p>Now we have the most basic components, we are ready to think about how we will decode instructions and wire the datapath. That will involve creating the control signals, logic relating to control signals, smaller intermediate components depending on what instructions need, and the pipeline registers. After we do that, all that should be left is hazard control, handling branches, and testing.</p> <p>For now, feel free to take a look at the <a href="https://github.com/samienr/risc-v-toy">source HDL code I have so far on my GitHub.</a> Until then, take care!</p> 2025-10-26T00:00:00+00:00 2025-10-26T00:00:00+00:00 Samien Rahman https://samienr.com/blog/designing-a-cpu-01/ <p>I've been wanting to practice my understanding of computer architecture ever since I completed <a href="https://users.ece.utexas.edu/~patt/24f.460n/">this course</a> during my studies. However, I didn't know Verilog at the time, so the most I could do was a cycle-accurate pipelined <a href="https://github.com/samienr/ECE460N/tree/main/lab6/submission">simulator</a>.</p> <p>The goal is to take this project to the next level: <strong>I'm going to make a synthesizable pipelined RISC-V core in RTL.</strong> The goal is simple: create a pipelined, in-order processor that can execute RV32I instructions.</p> <p>After I get some basic functionality, I will try to implement support for interrupts/exceptions. Then I'll explore caches, branch prediction, and out-of-order execution.</p> <h1 id="instruction-set-architecture">Instruction Set Architecture</h1> <p>The instruction set architecture (ISA) is the contract between hardware and software, meaning it defines how instructions are encoded, what registers exist, and what operations a CPU can perform. It is <strong>not</strong> the implementation details. In other words, it defines <em>what</em> the CPU can do, but doesn't dictate <em>how.</em></p> <p>Choosing the ISA is a <em>very significant</em> decision as it affects the CPUs fundamental design, and everything that builds on it. This includes instruction encoding, register file, and memory.</p> <p>Since the primary purpose of this project is the learning experience, I figured using the RV32I instruction set is a no-brainer. The abundance of resources due to RISC-V's open-source nature makes it a natural choice for such a learning exercise.</p> <p>With that in mind, I can start designing the individual logical components of the processor. I don't have the entire thing planned out yet, but I'm going to begin with the following components, then continue with whatever makes the most sense:</p> <ol> <li>ALU</li> <li>Register file</li> <li>Decoder + control signals</li> <li>We'll figure it out as we go</li> </ol> <p>Once I get everything working, I'll try to get this running on an FPGA.</p> <p>I'm optimistic I can get this done within a few months, but Murphy's Law <em>is</em> very much a thing.</p> 2024-06-14T00:00:00+00:00 2024-06-14T00:00:00+00:00 Samien Rahman https://samienr.com/blog/keyboard/ <p>I've been into custom mechanical keyboards for a while, but the absurdly high costs and long wait times for parts pushed me towards a different solution: designing and building a keyboard myself. As a college student, affordability and quick access are key, and the custom keyboard is just the opposite of that, so I decided to take on this project myself.</p> <p>I figured if I were going to design the keyboard entirely myself, I might as well make it as <em>custom</em> as possible. I was going to design this keyboard something <em>just for myself</em>.</p> <h1 id="design">Design</h1> <p>Within a few weeks of <a href="https://reddit.com/r/ErgoMechKeyboards">snooping around online</a>, I discovered a whole world of bizarrely-shaped, split keyboards. I very quickly became inspired by the <a href="https://github.com/kata0510/Lily58">Lily58</a> and the <a href="https://github.com/foostan/crkbd">Corne</a>. I learned that the motivation behind these strange layouts came from two goals that I had myself:</p> <ol> <li>Reducing finger movement</li> <li>Enhanced typing comfort</li> </ol> <p>Both of these goals are achieved by two design choices:</p> <ol> <li>Less keys = less places for my fingers to go</li> <li>Key placement matching the natural positioning of fingers— meaning a split layout</li> </ol> <p>To start, I mapped out a rough layout by tracing my finger movements using a painting app on an iPad. <img class=" no-hover " alt="Traced finger positions" src="finger_paint.png" /> </p> <figcaption>Super basic, I know.</figcaption> <p>That gave a basic idea of the where each finger naturally goes as I extend them.</p> <p>As for hardware, I chose:</p> <ul> <li><strong>Seeed Studio XIAO nRF52840</strong> microcontroller for its Bluetooth Low Energy capability, affordable price, and ARM architecture.</li> <li><strong>Kalih Choc Red switches</strong> for their low profile and because I like linear switches</li> </ul> <hr /> <h1 id="ergogen">Ergogen</h1> <p>I needed a tool to design the layout and found <a href="https://ergogen.cache.works/">Ergogen</a>. , which uses a simple YAML format to create layouts. Thanks to <a href="https://flatfootfox.com/ergogen-introduction/">a helpful blog series by FlatFootFox</a>, I defined a 3x6 grid for keys on each hand, matching the finger positions I had determined on the iPad. The flexibility of YAML allowed me to easily tweak the layout until it felt and looked right. Here's a snippet of my Ergogen config:</p> <pre data-lang="yaml" style="background-color:#212733;color:#ccc9c2;" class="language-yaml "><code class="language-yaml" data-lang="yaml"><span> </span><span style="color:#73d0ff;">columns</span><span style="color:#ccc9c2cc;">: </span><span> </span><span style="color:#73d0ff;">outer</span><span style="color:#ccc9c2cc;">: </span><span> </span><span style="color:#73d0ff;">key</span><span style="color:#ccc9c2cc;">: </span><span> </span><span style="color:#73d0ff;">splay</span><span style="color:#ccc9c2cc;">: </span><span style="color:#ffcc66;">10 </span><span> </span><span style="color:#73d0ff;">pinky</span><span style="color:#ccc9c2cc;">: </span><span> </span><span style="color:#73d0ff;">key</span><span style="color:#ccc9c2cc;">: </span><span> </span><span style="color:#73d0ff;">stagger</span><span style="color:#ccc9c2cc;">: </span><span style="color:#ffcc66;">3 </span><span> </span><span style="color:#73d0ff;">ring</span><span style="color:#ccc9c2cc;">: </span><span> </span><span style="color:#73d0ff;">key</span><span style="color:#ccc9c2cc;">: </span><span> </span><span style="color:#73d0ff;">stagger</span><span style="color:#ccc9c2cc;">: </span><span style="color:#ffcc66;">8 </span><span> </span><span style="color:#73d0ff;">splay</span><span style="color:#ccc9c2cc;">: </span><span style="color:#ffcc66;">-4</span><span style="color:#ccc9c2cc;">.</span><span style="color:#ffcc66;">1 </span><span> </span><span style="color:#73d0ff;">spread</span><span style="color:#ccc9c2cc;">: </span><span style="color:#bae67e;">1.035kx </span><span> </span><span style="color:#73d0ff;">middle</span><span style="color:#ccc9c2cc;">: </span><span> </span><span style="color:#73d0ff;">key</span><span style="color:#ccc9c2cc;">: </span><span> </span><span style="color:#73d0ff;">stagger</span><span style="color:#ccc9c2cc;">: </span><span style="color:#bae67e;">.25*ky </span><span> </span><span style="color:#73d0ff;">splay</span><span style="color:#ccc9c2cc;">: </span><span style="color:#ffcc66;">-5 </span><span> </span><span style="color:#73d0ff;">spread</span><span style="color:#ccc9c2cc;">: </span><span style="color:#bae67e;">1.04kx </span><span> </span><span style="color:#73d0ff;">index</span><span style="color:#ccc9c2cc;">: </span><span> </span><span style="color:#73d0ff;">key</span><span style="color:#ccc9c2cc;">: </span><span> </span><span style="color:#73d0ff;">stagger</span><span style="color:#ccc9c2cc;">: </span><span style="color:#bae67e;">-.65*ky </span><span> </span><span style="color:#73d0ff;">splay</span><span style="color:#ccc9c2cc;">: </span><span style="color:#ffcc66;">-1 </span><span> </span><span style="color:#73d0ff;">inner</span><span style="color:#ccc9c2cc;">: </span><span> </span><span style="color:#73d0ff;">key</span><span style="color:#ccc9c2cc;">: </span><span> </span><span style="color:#73d0ff;">stagger</span><span style="color:#ccc9c2cc;">: </span><span style="color:#bae67e;">-.5*ky </span><span> </span><span style="color:#73d0ff;">rows</span><span style="color:#ccc9c2cc;">: </span><span> </span><span style="color:#73d0ff;">bottom</span><span style="color:#ccc9c2cc;">: </span><span> </span><span style="color:#73d0ff;">home</span><span style="color:#ccc9c2cc;">: </span><span> </span><span style="color:#73d0ff;">top</span><span style="color:#ccc9c2cc;">: </span><span> </span><span style="color:#73d0ff;">thumb</span><span style="color:#ccc9c2cc;">: </span><span> </span><span style="color:#73d0ff;">key</span><span style="color:#ccc9c2cc;">: </span><span> </span><span style="color:#73d0ff;">padding</span><span style="color:#ccc9c2cc;">: </span><span style="color:#bae67e;">ky </span><span> </span><span style="color:#73d0ff;">spread</span><span style="color:#ccc9c2cc;">: </span><span style="color:#bae67e;">kx </span><span> </span><span style="color:#73d0ff;">anchor</span><span style="color:#ccc9c2cc;">: </span><span> </span><span style="color:#73d0ff;">ref</span><span style="color:#ccc9c2cc;">: </span><span style="color:#bae67e;">matrix_index_bottom </span><span> </span><span style="color:#73d0ff;">shift</span><span style="color:#ccc9c2cc;">: </span><span>[</span><span style="color:#ffcc66;">2</span><span style="color:#ccc9c2cc;">,</span><span style="color:#ffcc66;">-28</span><span>] </span><span> </span><span style="color:#73d0ff;">columns</span><span style="color:#ccc9c2cc;">: </span><span> </span><span style="color:#73d0ff;">left</span><span style="color:#ccc9c2cc;">: </span><span> </span><span style="color:#73d0ff;">key</span><span style="color:#ccc9c2cc;">: </span><span> </span><span style="color:#73d0ff;">shift</span><span style="color:#ccc9c2cc;">: </span><span>[</span><span style="color:#ffcc66;">-1</span><span style="color:#ccc9c2cc;">,</span><span style="color:#ffcc66;">0</span><span>] </span><span> </span><span style="color:#73d0ff;">splay</span><span style="color:#ccc9c2cc;">: </span><span style="color:#ffcc66;">-15 </span><span> </span><span style="color:#73d0ff;">middle</span><span style="color:#ccc9c2cc;">: </span><span> </span><span style="color:#73d0ff;">key</span><span style="color:#ccc9c2cc;">: </span><span> </span><span style="color:#73d0ff;">splay</span><span style="color:#ccc9c2cc;">: </span><span style="color:#ffcc66;">-7</span><span style="color:#ccc9c2cc;">.</span><span style="color:#ffcc66;">5 </span><span> </span><span style="color:#73d0ff;">right</span><span style="color:#ccc9c2cc;">: </span><span> </span><span style="color:#73d0ff;">key</span><span style="color:#ccc9c2cc;">: </span><span> </span><span style="color:#73d0ff;">splay</span><span style="color:#ccc9c2cc;">: </span><span style="color:#ffcc66;">-15 </span><span> </span><span style="color:#73d0ff;">shift</span><span style="color:#ccc9c2cc;">: </span><span>[</span><span style="color:#ffcc66;">2</span><span style="color:#ccc9c2cc;">.</span><span style="color:#ffcc66;">6</span><span style="color:#ccc9c2cc;">,</span><span style="color:#ffcc66;">-2</span><span>] </span><span> </span><span style="color:#73d0ff;">rows</span><span style="color:#ccc9c2cc;">: </span><span> </span><span style="color:#73d0ff;">cluster</span><span style="color:#ccc9c2cc;">: </span></code></pre> <p>I used <a href="https://github.com/ceoloide/ergogen-footprints/tree/main">Ceoloide's</a> footprint for the switch footprints, which are reversible, meaning that both halves of the board can use the same PCB design.</p> <img class=" no-hover " alt="Preview of layout in ergogen online tool" src="ergogen_preview.png" /> <figcaption>Preview of layout generated in Ergogen</figcaption> <hr /> <h1 id="pcb-design">PCB Design</h1> <p>Ergogen generated a KiCad file with the board outline and switch footprints. I had to create and route the traces. Additionally, the footprint I used for the nRF52840 didn't account for its battery pads, so I had to modify the footprint by adding a small cutout to route battery wires through. I haven't messed around with PCBs before this besides some basic designs from school, so that was a nice learning experience. The supportive community on the <a href="https://discord.gg/kk4rXYkp4H">Absolem Club Discord server</a> helped me through the process.</p> <img class=" no-hover " src="KiCad_before.png" /> <figcaption>The PCB Ergogen generated</figcaption> <img class=" no-hover " src="KiCad_after.png" /> <figcaption>After adding traces and adjusting the microcontroller footprint</figcaption> <p>Once all the electronics were in place, I decided to add some decorative patterns to the pcb, as I decided not to use a plate on this keyboard. <img class=" no-hover " src="final_pcb.png" /> And with that, the PCB design was pretty much done. All that was left was ordering everything and putting it all together.</p> <h1 id="assembly-and-firmware">Assembly and Firmware</h1> <p>I ordered my PCB from <a href="https://jlcpcb.com/">JLCPCB</a> in black and white for about 20 USD, the microcontroller from <a href="https://www.seeedstudio.com/">SeeedStudio</a>, and the other components from <a href="https://typeractive.xyz/">Typeractive</a>.</p> <p>I used my university's makerspace for soldering, learning about reflow soldering for smaller components.</p> <h2 id="keymap">Keymap</h2> <p>First, I defined the keymap. I opted for Colemak-DH, as it was designed to be a more ergonomic layout that also allows for faster typing speeds. The other layers were designed by seeing various designs online and then just iterating.</p> <p>I had initially set out to write the keymap directly to the ZMK keymap file, but I quickly found <a href="https://nickcoutsos.github.io/keymap-editor/">Keymap Editor</a>, an online tool that can connect to a ZMK repository on GitHub and manage the keymaps with a very easy to use GUI. I used the tool to create these keymaps:</p> <img class=" no-hover " src="default_layer.png" /> <figcaption>Default layer</figcaption> <img class=" no-hover " src="symbol_layer.png" /> <figcaption>Symbol layer</figcaption> <img class=" no-hover " src="number_layer.png" /> <figcaption>Number layer</figcaption> <img class=" no-hover " src="tri_layer.png" /> <figcaption>Function layer</figcaption> <img class=" no-hover " src="gaming_layer.png" /> <figcaption>Gaming layer</figcaption> <p>I also decided to make another layer for gaming to keep the WASD layout, but I haven’t been able to test how effective this is.</p> <h2 id="firmware">Firmware</h2> <p>I then opted for the ZMK Firmware, namely because QMK does not support wireless boards due to some licensing issues with Bluetooth, and because I do intend on learning Zephyr eventually, which ZMK is based on.</p> <p>I began by mapping the pins on the microcontroller to the corresponding columns and rows of the keyboard matrix. I probably should’ve planned these before designing the PCB, but I chose these pins retroactively, as the PCB traces were already routed.</p> <table><thead><tr><th>Pin Number</th><th>Digital</th><th>Matrix mapping</th></tr></thead><tbody> <tr><td>P0.02</td><td>0</td><td>Outer Column</td></tr> <tr><td>P0.03</td><td>1</td><td>Pinky Column</td></tr> <tr><td>P0.28</td><td>2</td><td>Middle Column + outerthumb</td></tr> <tr><td>P0.29</td><td>3</td><td>Index Column + middlethumb</td></tr> <tr><td>P0.04</td><td>4</td><td>Inner Column + innerthumb</td></tr> <tr><td>P1.12</td><td>7</td><td>Upper Row</td></tr> <tr><td>P1.13</td><td>8</td><td>Middle Row</td></tr> <tr><td>P1.14</td><td>9</td><td>Lower Row</td></tr> <tr><td>P1.15</td><td>10</td><td>Thumb Row</td></tr> </tbody></table> <h3 id="creating-the-shield">Creating the shield</h3> <p>Because this keyboard was completely original, there wasn’t a pre-existing shield, so I had to make my own. That wasn’t so bad. The <a href="https://zmk.dev/docs/development/new-shield">ZMK documentation</a> is very well written and easy to follow.</p> <p>All that was left was to compile and flash the firmware! <small>Not Really</small></p> <h1 id="trouble-in-paradise">Trouble in Paradise</h1> <p>Despite the careful planning and assembly, I ran into a significant issue: the left half of the keyboard worked perfectly and paired with my devices, but the right half was unresponsive.</p> <h3 id="initial-diagnosis">Initial Diagnosis</h3> <p>I tried resetting the firmware, suspecting an issue with the pairing process. This fixed the issue in that the right half now connected, but it also led me to find another problem: most keys on the right half were unresponsive, and pressing the top key in each column caused all keys in that column to ghost.</p> <h3 id="physical-troubleshooting">Physical Troubleshooting</h3> <p>I grabbed a multimeter to test each diode, as my soldering job for the right half was particularly ugly, but each diode was functioning correctly. Next, I tested each diode-switch pair, where I did find an inconsistency in voltages. I then tried flipping all the diodes, as perhaps the direction needed to be flipped because the board was flipped, but this yielded no change. It was time to take a look at the PCB.</p> <h3 id="pcb-analysis">PCB Analysis</h3> <p>I next decided to take a look at the PCB layout. This is where I found the culprit. I discovered that I had forgotten to route one of the pads on the backside (the front for the right side of the board). Fortunately, because the left and right halves of the board use the same PCB, I was able to simply resolder the microcontroller to the back side of the right half. I knew this would work because the left side worked flawlessly, and although the diode pads were on the other side, all the switch connections were through-holes, so the side on which they were installed would not matter. All that was left was to compensate with software by reversing the order of the pins. This finally worked.</p> <h1 id="conclusion">Conclusion</h1> <p>This project was a bit challenging but very rewarding, providing me with a custom mechanical keyboard tailored to my preferences. It was also my first truly original electronics project, and it taught me a lot about PCB design and soldering, all through practical hands-on experience. This project also helped in refining my independent problem-solving skills, as I am used to having either documentation or peers to take help from. I hope this inspires others to try their hand at DIY keyboard building!</p> <h2 id="open-source">Open Source (?)</h2> <p>I've finally open sourced the keyboard design files on <a class="external" href="https://github.com/samienr/SOR-Hydrogen">this Github repository.</a> I haven't yet fixed the PCB routing mistake, though I do plan on getting to it eventually. It's just not a high priority at the moment. Feel free to do whatever you want with the designs, this project was more for the learning experience.</p> <h1 id="next-steps">Next Steps</h1> <p>I'm probably going to work on a case for the boards next. The goal as it stands now is to create a model for 3D printing just to protect the boards (and the surfaces I put them on), then to eventually design a case for either CNC milling or resin printing that holds the boards at the most comfortable angles for me.</p> <img class=" " src="keyboard.jpg" /> <figcaption>The completed product</figcaption>