Hardcaml MIPS CPU Learning Project and Blog

Tl;dr: I’m writing a blog about making a MIPS CPU in Hardcaml.

Hi! My name is Sasha, and I’m a student at Penn State majoring in CS and Math. Last semester, I took a computer engineering class where we built a pipelined MIPS CPU in Verilog as a semester-long project. I enjoyed the class, but a lot of frustration came from Verilog itself.

A few months ago, I came across the Signals and Threads Programmable Hardware episode. I really liked the idea of Hardcaml: a library to write and test hardware designs in OCaml. Representing circuits as functions felt like a good abstraction, and I’ve been wanting to learn OCaml for a while.

So this summer, a friend and I are rewriting the Verilog MIPS CPU we made last semester into Hardcaml. We’re still working on the project, but have made some good progress and wanted to share it in case anyone finds it interesting / useful. If anyone wants to take a look, it’s up on GitHub.

We’ve written some blog posts about our project:

  1. Some more background on what we’re doing and why
  2. An ELI5 overview of how hardware, and pipelined CPUs in particular, work
  3. Another high-level overview of Verilog, hardware design, FPGAs, and why I think OCaml might be a great fit for hardware design
  4. How to set up a Hardcaml project, including testing and Verilog generation
  5. How to split Hardcaml circuits into multiple modules

There’s also a few more that we’ve written code for, but are still drafting blog posts about:

  • How to work with memory in Hardcaml
  • How to design stateful, sequential circuits in Hardcaml
  • A safer design pattern for Hardcaml circuits

I’m new to both OCaml and blogging, and this has definitely been a fun experience so far! Would love to hear any feedback / comments.

44 Likes

Hi,
I just want to say it’s a great project. There doesn’t seem to be many resources on hardcaml so I look forward to reading the blog!

1 Like

This is a really wonderful series of blogs! Can we convince you to have a go at a simple RISC-V CPU once you have MIPS working? :slight_smile:

4 Likes

I’m glad the episode struck a chord, and I’m excited to see what comes of your experiment. Good luck!

2 Likes

Very cool - really enjoying the blog posts!

If you have any questions, suggestions or feedback for Hardcaml, please do open issues on Github.

And here’s a deal - if you can run a compiled program in the Hardcaml simulator, I’ll buy you and your colleague an Arty A7 board to run it on.

5 Likes

Thank you all for the kind words and support! This has been a fun project so far, and now that we’re starting to get comfortable with Hardcaml, I’m hoping to have more updates soon.

That’s a great idea! Once we get the core parts in place, there’s a few things I’d like to improve/add to the basic version we made in class. For instance, we’re initially implementing instruction memory as a mux, which is simple but not that realistic. I’d like to play around with the Xilinx memory library and try to get it working with actual RAM. Rewriting this project into a RISC-V CPU could be a fun challenge!

Absolutely! We’ve been keeping track of some “Hardcaml observations” in each post. Once we’ve gotten a bit more comfortable with the library and ecosystem, we’ll try and distill that into something useful.

Wow, thanks! With the magic powers of Hardcaml behind us, it should be doable :smile:

1 Like

Nice blog posts!

If you want an example of Hardcaml on Arty A7, do have a look at this example

Regardless of whether you use the Arty A7, src/infrastructure/uart.ml contains some ~non-trivial code examples for state machines.

2 Likes

:+1: Does your website have an RSS feed?

It does now! https://ceramichacker.com/rss.
Also https://ceramichacker.com/atom for Atom users.

On a side note, we’ve published two more posts:

  1. Memory in Hardcaml
  2. Registers and Stateful Design

More coming soon!

3 Likes

Hi everyone! We are excited to announce that we have completed this project and blog. Progress has been slow these past few months due to work, internships, and college, but we’ve now released v1.0.0 on GitHub. We also published posts on:

Finally, we published a conclusion blog post, which wraps up some strengths/weaknesses of Hardcaml, as well as some takeaways on OCaml and blogging more generally.

Thank you to @andyman and @fyquah95 for building Hardcaml, and for helping us out on GitHub issues! We really appreciate your time and suggestions.

Overall, we’ve come to the conclusion that Hardcaml is a much better tool for hardware design than Verilog. This has been a great experience, and we walk away with a better understanding of hardware, functional programming, and technical writing.

14 Likes

@askvortsov amazing project and nice read! By the way, you might be interested in this discussion about joining the forces to choose one common low-level IR instead of using Verilog as the intermediate representation. So far most interesting candidates were FIRRTL, CIRCT (LLVM/MLIR-based language and a toolset, they support FIRRTL as well). Back in time I suggested for Hardcaml to support FIRRTL as well, while they are not against the merge if someone will implement it, they seem to reluctant to spend efforts on adding it themselves.

1 Like

Hi everyone! Last fall, we completed our original plan for this project, rewriting the verilog MIPS CPU we had designed for a class into Hardcaml. A few weeks later, we got an invite to video-meet with the Hardcaml team to talk about our experience. They even sent us actual Arty A-7 FPGAs so we could test out our simulation on real hardware!

Junior year ended up much busier than expected, and although we had gotten our code onto the FPGAs by January, we’ve only just now fully finished our project. Our blog now has 2 bonus installments:

  1. Running Hardcaml on an actual FPGA. Here, we lit up LEDs to display the output of a hardcoded program.
  2. Hardcaml MIPS and I/O. Here, we restructured our CPU so that programs can communicate with an external device using UART.

With these changes, our full design is now a simplified but realistic processor that can run meaningful programs.

Thank you very much to @andyman, @fyquah95, Ben Devlin, and the rest of the Jane Street FPGA team for creating Hardcaml, meeting with us, and answering our numerous questions throughout this process. Thank you also to @yaron_minsky and Jane Street for sending us the FPGAs to try out our code.

This has been an incredibly interesting, challenging, and rewarding journey. We hope that our blog posts and sample project are useful for learning Hardcaml in the future, and welcome any questions or comments.

16 Likes