package ppx_hardcaml

  1. Overview
  2. Docs
Rewrite OCaml records for use as Hardcaml Interfaces

Install

Dune Dependency

Authors

Maintainers

Sources

v0.17.0.tar.gz
sha256=e4ea96d3edd794a1e3128b9c42eb97da41c95c78371caa1e9cd6842244766e1c

Description

An interface in Hardcaml is an OCaml record with special attributes including a bit width and RTL netlist name. Input and output ports of a hardware design can then be accessed through the OCaml record. This allows easier management of bundles of ports when working with the Simulator, Netlist generation or hierarchical designs.

Published: 26 May 2024

README

ppx_deriving Plugin for Hardcaml

This ppx supports grouping collections of signals using OCaml records. It generates a set of functions that can be used to process the fields of the record, associate bit witdths and manage generated RTL names.

We generally call a collection of signals an interface.

Such interfaces may be nested and include arrays and list typed fields.

It must be used in conjunction with [@@deriving sexp_of], like this:

type 'a t =
  {
    ...
  }
[@@deriving sexp_of, hardcaml]

Example

module S = struct
  type 'a t =
    { signal : 'a [@bits 6]
    ; signal_list : 'a list [@length 2]
    ; signal_array : 'a array [@length 3] [@bits 7]
    ; sub_interface : 'a T.t [@rtlmangle true] (* where [T.t] also derives hardcaml *)
    }
  [@@deriving sexp_of, hardcaml]
end

The generated code

The type generated by the ppx is exactly as specified. It is a record with each field of type 'a. There may be only one polymorphic type and each field must have this type. The ppx only generates related functions and values.

Bit widths

Simple fields take an optional bit width specification.

foo : 'a [@bits 8]

These specifications do not have to be constants.

foo : 'a [@bits n + 1]

If not provided, a default bit width of 1 inferred.

Lengths

When specifying list and array fields, a length must be provided.

foo : 'a array [@length 6]

Naming

By default the name of the field will be will be used by Hardcaml libraries to generate an RTL signal identifier. Sometimes this is not appropriate (ie OCaml names are not always valid Verilog or VHDL names) so a number of attributes are available to rename fields.

Naming field attributes

foo : 'a [@rtlname "bar"]

The field foo will be called bar in the RTL.

foo : 'a [@rtlprefix "bar_"]
foo : 'a [@rtlsuffix "_bar"]

The field name will be combined with the pre/suffix to produce bar_foo or foo_bar

foo : 'a Foo.t [@rtlprefix "foo_"]
foo : 'a Foo.t [@rtlmangle true]

Each field in [Foo.t] will be prefixed with foo_. The rtlmangle attribute does this prefixing automatically based on the outer field name.

Global naming options

The naming attributes can be applied to all fields at once as follows

[@@deriving sexp_of, hardcaml ~rtlprefix:"foo_"]

Generated API

For the complete API see Hardcaml.Interface.Pre and Hardcaml.Interface.S.

The PPX generates the functions for Hardcaml.Interface.Pre. These include map and iter functions for transforming and accessing each field in turn, map2 anmd iter2 for combining interfaces, to_list to get a list of fields and a value t : (string * int) t which includes each fields name and bit width.

A more extensive API is built from these primitives.

Examples

Assign a group of signals to some wires

X.map2 x_wires x_signals ~f:(<==)

Create an constant instance of an interface set to 0:

X.Of_signal.const 0

Define a hardware module via it's input and output ports, and an implementation function. Convenience functors in Hardcaml generate RTL circuits, hierarchical designs, simulators etc based on this pattern.

module Input_ports = struct
  type 'a t = {...}[@@deriving sexp_of, hardcaml]
end

module Output_ports = struct
  type 'a t = {...}[@@deriving sexp_of, hardcaml]
end

let create (i : _ Input_ports.t) = { Output_ports. ... }

Dependencies (6)

  1. ppxlib >= "0.28.0"
  2. dune >= "3.11.0"
  3. ppx_jane >= "v0.17" & < "v0.18"
  4. hardcaml >= "v0.17" & < "v0.18"
  5. base >= "v0.17" & < "v0.18"
  6. ocaml >= "5.1.0"

Dev Dependencies

None

Used by (9)

  1. hardcaml_axi >= "v0.17.0"
  2. hardcaml_c >= "v0.17.0"
  3. hardcaml_circuits >= "v0.17.0"
  4. hardcaml_handshake >= "v0.17.0"
  5. hardcaml_of_verilog >= "v0.17.0"
  6. hardcaml_verify >= "v0.17.0"
  7. hardcaml_verilator >= "v0.17.0"
  8. hardcaml_xilinx >= "v0.17.0"
  9. hardcaml_xilinx_reports >= "v0.17.0"

Conflicts

None

OCaml

Innovation. Community. Security.