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]
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 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.
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.
When specifying list and array fields, a length must be provided.
foo : 'a array [@length 6]
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.
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.
The naming attributes can be applied to all fields at once as follows
[@@deriving sexp_of, hardcaml ~rtlprefix:"foo_"]
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.
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. ... }