To focus the search input from anywhere on the page, press the 'S' key.
in-package search v0.1.0
Install
Authors
Maintainers
Sources
sha256=4f0c0be1547edd7d2e0754c3333c42411712362c9c2792a15da78c1ceba81b94
README.md.html
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 : sig
type 'a t =
{ signal : 'a[@bits 6]
; signal_list : 'a list[@length 2]
; signal_array : 'a array[@bits 3][@bits 7]
; sub_interface : 'a T.t[@rtlmangle] (* 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]
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 includemap
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. ... }