Hardcaml: An OCaml Hardware Domain-Specific Language for Efficient and Robust Design

The core type in a Hardcaml circuit is the Signal.t type. Various functions and operators that take Signal.t as parameters represent hardware primitives. Table 1 shows a few examples of these.

All operators contain a : to distinguish them between regular OCaml operators on integers, as OCaml does not support operator overloading. There are multiple variants of arithmetic operators (eg: +: and +:.). The +: and +:. operators both represent addition. +: operates on two Signal.ts that must match bit-width, while +:. operates on a Signal.t and integer that has its bit-width inferred. reg_specs specify clock and clear signals for sequential logic such as regs. mux is a general multiplexor that takes a list of arguments, and mux2 is a convenient helper function to write a simple if-then-else multiplexor with two cases.

The programmer can create a hardware circuit by calling functions on a value of type Signal.t, and then storing the returned value (which is also a Signal.t). For example, the following function creates a counter that counts to count_to and then wraps back to zero.~ is used to pass a named argument to a function, and () is sometimes necessary to terminate a sequence of function arguments in OCaml.

The code listing above constructs a counter which behaves similarly to the Verilog code snippet below.

The advantage of using Hardcaml here is it will prevent the counter output connecting to something that isn’t wide enough, which if happened in Verilog would silently drop the unused bits.

Hardcaml can represent each logical idea in its own type, defined by the programmer. OCaml’s type system then statically guarantees that values of a given type cannot be used in ways other than those defined valid for that type. This enables both abstraction and eliminates entire classes of potential errors. Note that these types are parameterized with ’a, later to be replaced with Signal.ts. For example, the following Hardcaml snippet defines a type called Rectangle.t, which has a 10-bit length and a 6-bit width. Signal.t Rectangle.t is similar to a Rectangle<Signal> in Java or C++. A parameterized type argument allows us to use Rectangle.t in different contexts, like tests, debugging, and HDL generation.

You can then write a function that takes a Rectangle.t as an argument. This snippet would generate a circuit that outputs the area of a given rectangle.

[@@deriving hardcaml] instructs the Hardcaml preprocessor to generate utility functions working with the Rectangle.t type. The derived Rectangle.map function applies a function to every field. For example, this function returns a rectangle where both the length and width are increased by a certain size.

Another derived function is Rectangle.Of_signal.priority_select, which performs a combinational priority select on the custom rectangle type. For example, this function takes a list of rectangles and outputs the first rectangle whose width is greater than threshold. It uses List.map to convert the Rectangle.t inputs to With_valid.t objects. A With_valid.t object contains an input rectangle (value) and a single bit indicating whether the priority select should accept the input (valid).

Custom types can be nested arbitrarily to create multiple layers of logical separation. For example:

Another abstract type that one would define is a scalar-type. These are bit-vectors of a particular width that have logical meaning. For example, we can define a 32-bit price in US dollars. It’s important that we don’t use values of this type when we’re expecting, for example, Euros. We then can define some custom functions that operate on this type, namely is_gte_zero, min, and max. Including the module Types.Scalar creates a type Price_in_usd.t and common functions on that type.

Functions can be defined to explicitly expect a value of type Price_in_usd.t, rather than an arbitrary value of type Signal.t.

The OCaml compiler will permit the following.

On the other hand, the OCaml compiler will emit a compile-time error due to a type mismatch in the following code snippet. This is an important safety feature of Hardcaml as it prevents the programmer from passing values of unexpected types into functions.

Here is another example of a compile-time error due to a type mismatch as the programmer uses the type Signal.t Rectangle.t instead of Signal.t Price_in_usd.t, producing the error

These scalar types can also be nested within interfaces.

A Hardcaml circuit module can be structured similar to a Verilog circuit module. Using the hierarchy library inside Hardcaml, a global circuit hierarchy can be constructed. This produces simulation waveforms with hierarchical signals which increases debugging productivity, and generates RTL with hierarchical modules, which works better with existing Verilog and VHDL-based vendor tooling.

To define a Hardcaml circuit module, the programmer defines I and O modules, corresponding to the input and output interfaces. Then, the programmer defines a create function that when given Signal.t I.t, returns Signal.t O.t. For example:

Hardcaml handles bit-width strictly. The circuit construction step validates bit-widths for all operations before running simulations or generating Verilog. This prevents many errors at the compilation stage, increasing the speed of the designer’s feedback loop. For example, the following program will fail due to a width mismatch:

Hardcaml can also infer the bit-width for most operations, so users don’t need to specify the width for most internal wires. In the case above we specifically resized our wires to 32-bits and 16-bits.

For example, Hardcaml will infer the width of mult_result as width a + width b and the width of eq_result as 1.

During circuit elaboration, Hardcaml also performs other validation, ensuring that:

• •

  Module instantiations have appropriate port widths.

• •

  All wires have exactly one driver.

• •

  Operation bit-widths match.

These errors are caught early on before simulation is run or RTL is generated.

Hardcaml includes the Always DSL, which can describe circuits in the same style as a Verilog always block. Signals are now inside guarded assignments, either as asynchronous wires or synchronous regs. The Always DSL does not support blocking assignments. Below we show an example of an accumulating sum state machine written in this style. This module will add and accumulate all inputs provided as long as any input is non-zero.

First we define a clock and clear module Control which will ensure other modules types cannot drive this circuit. This is then combined with our data inputs which is an OCaml list of signals, each with a bit-width of 4. Our output is a single signal of bit-width 4.

We then define the the states our circuit can be in with the module State, which are Idle and Adding. We use the preprocessor to automatically derive functions that let Hardcaml internally compare and enumerate in order to implement the state machine.

The Always DSL create function takes this module as its input and returns sm, the control object of our state machine.

Inside the create function’s control input, we have expanded out the clock and clear inputs, which means the named arguments for Reg_spec.create match and do not need to be specified, reducing the chance of a connection typo.

We then declare the output O.t as an always reg– this means we can use the Always DSL logic assignment operator (<--) to assign values to our output from within our state machine. For each state, we add logic for transitioning to new states and assigning output values. We use the Hardcaml tree and reduce functions to construct a log2 tree that will sum elements. This demonstrates how optimized data structures can be used with low effort on the designers part. The preprocessor generates a function O.Of_always.value that converts our always reg to a Signal.t O.t.

The Always DSL allows for further abstraction by using OCaml functions. This also can provide implicit documentation via function names in complicated state machines.

In OCaml a functor is a module that takes one or more modules as a parameter, and returns a new module. These allow us to parameterize Hardcaml circuits, similar to Verilog’s parameters. The programmer first defines a config argument for the parameterized module. For example:

Then, they can define the corresponding circuit and module using fields (metadata_bits) or datatypes (Data.t) from the functor argument. The module Make below is an OCaml functor.

The functor can then be instantiated with an argument of the appropriate type signature. For example:

This is similar to parameterized circuits in Verilog. The key advantage to this functor-style is that the parameters themselves can be arbitrary arguments, such as lists, integers, arrays or even custom types (Data.t in the above case). This allows for high expressiveness in parameter descriptions. When instantiating the Make functor, the OCaml compiler will ensure that the provided argument value matches its expected type.

Functors, as demonstrated above, are a powerful feature in OCaml that allows modularity and parametrization. This demonstrates an advantage of Hardcaml being embedded in a programming language: it allows the programmer to leverage existing software-level features for hardware design.

Below are some examples of circuit description that demonstrate Hardcaml’s expressiveness.

Hardcaml also provides the hardcaml_fixed_point library, with support for hardware-synthesizable arithmetic operations such as +, -, and *. It provides a rich set of rounding and clamping modes, and seperate types for performing signed or unsigned operations. This library is useful for many signal processing applications, where explicit control over integer and fractional bit-widths is required. Functors can be used with this library to implement and experiment different bit-widths and the resulting change of output precision.

One of the aspects of Hardcaml that sets it apart from other DSLs is its emphasis and support for circuit testing, simulation, and verification. The next sections highlight the technologies that are provided with Hardcaml for this purpose.

Although Hardcaml has been able to build upon the advantages other DSLs offer, there are still several shortcomings when compared to Verilog and VHDL.

• •

  Unless specifically labeled, the mapping of Hardcaml function calls to their generated RTL might not be obvious to a user, which can be important when debugging timing violations in Vivado.

• •

  Interfacing with externally written IP cores requires blackbox wrappers in Hardcaml which can’t be simulated, without doing additional work such as importing the RTL into Hardcaml.

• •

  The user may not be familiar with functional programming or OCaml.

We are continuously adding new features to Hardcaml and releasing improvements into open source repositories. We plan to implement the following new features that will further differentiate Hardcaml from other DSLs:

We used the Config module, shown below, to parameterize our design. We could easily change bit widths, window bounds, and circuit partitioning over the 3 Super Logic Regions (SLRs) available to us on the FPGA. Within seconds of making a change, the Dune build system would tell us if any of our tests failed, or if our design’s performance changed. In Verilog, we would not have been able to parameterize our design to this degree, and iterating over the design space would have taken much longer.

Inserting registers to pipeline a design is a common method to improve throughput. Doing this in Hardcaml was very easy due to the auto-generated utility functions on our custom types. The following code creates a new module foo, which uses a pipelined version of the AXI stream my_stream. We create the pipelined stream using Stream.Source.map, which creates a register for each signal in my_stream and registers all downstream connections.

In Verilog this would involve multiple registers for the different signals in the bus such as tlast, tvalid, tdata, an always block, and correct assignment to the downstream block.

Hardcaml MSM contains a multi-stage pipelined elliptic curve point adder. Hardcaml allows us to easily break the computation into several stages. A simplified form of this pattern looks something like the following:

This design pattern has two major benefits:

1. 1.

   Within a pipeline stage, all the signals are combinational, which avoids using a signal from a different pipeline stage that represents a different calculation

2. 2.

   Different pipeline stages can easily be tested in isolation

This project required a lot of modulo arithmetic on very large numbers. We used existing OCaml libraries zarith and bigint, which worked with Hardcaml even though they were written for OCaml software programs.