Module Hardcaml_kernel.Clocked_signalSource

Clocked_signal.t is similar to a Signal.t, but with clock domain info attached to it.

Sourcetype t
Sourcetype info

Information tracked by the signal.

Sourceval info : t -> info

Get the information attached to a signal.

Sourceval set_info : t -> info:info -> t

Set the information attached to a signal.

Naming

One or more string names applied to a signal. These will be used during RTL code generation and simulation to aid design inspection.

Sourceval names_and_locs : t -> Name_and_loc.t list

Returns the list of names and locations assigned to the signal.

Sourceval names : t -> string list

Returns the list of names assigned to the signal.

Sourceval set_names : t -> Name_and_loc.t list -> unit

Set the given names on the signal. Wipes any names currently set.

Sourceval reset_names : unit -> unit

Reset any names for global signals.

Attributes

Attributes are attached to signals and written during RTL generation. They can be used to control downstream synthesis and place and route tools. They do not otherwise affect the Hardcaml circuit.

Sourceval add_attribute : t -> Rtl_attribute.t -> t

Add an attribute to node.

Sourceval attributes : t -> Rtl_attribute.t list

Returns attributes associated to the signal.

Sourceval set_wave_format : t -> Wave_format.t -> unit

Set the format used to display the signal

Sourceval (--$) : t -> Wave_format.t -> t

Comments

A comment can be associated with a signal, and this is sometimes useful to pass information to downstream tooling (specifically Verilator).

Sourceval set_comment : t -> string -> t

Set the comment associated with the signal. This is currently only supported in Verilog.

Sourceval unset_comment : t -> t

Remove the comment associated with the signal. This is currently only supported in Verilog.

Sourceval comment : t -> string option

Returns comment associated with the signal.

Sourceval add_mux_waiver_exn : t -> int Coverage_prim.Waiver.t -> t

Attach a waiver for mux coverage. Raises if the signal is not a mux.

Sourceval add_cases_waiver_exn : t -> Coverage_prim.Case.t Coverage_prim.Waiver.t -> t

Attach a waiver for cases coverage. Raises if the signal is not a cases signal.

Sourceval add_register_waiver_exn : t -> Coverage_prim.Toggle.t Coverage_prim.Waiver.t -> t

Attach a waiver for register coverage. Raises if the signal is not a register or it is an always state register.

Sourceval add_always_state_waiver_exn : t -> string Coverage_prim.Waiver.t -> t

Attach a state waiver to an always state register. Raises if the signal is not an always state register.

Sourceval add_always_state_transition_waiver_exn : t -> string Coverage_prim.Transition.t Coverage_prim.Waiver.t -> t

Attach as transition wavier to an always state register. Raises if the signal is not an always state register.

Circuit Input and Output Ports

Specification of the module level input and output ports. Ports are represented in Hardcaml as wires with a single name. Note that Hardcaml will generally rewrite and legalize names depending on context but will not do so for ports.

Sourceval input : string -> int -> t

Creates an input.

Sourceval output : string -> t -> t

Creates an output.

Wires

Wires are used in Hardcaml to conenct two signals together. They are first created then assigned to (internally they have a mutable reference to their driver). Wires are how we can create cycles which we require in order to build logic like, for example, a counter.

It is entirely possible to create combinational loops using wires. Often this is not the intent and Hardcaml has functions to detect this - for example, Cyclesim will fail if there is such a loop.

Sourceval wire : int -> t

Creates an unassigned wire.

Sourceval wireof : t -> t

Creates an assigned wire.

Sourceval (<--) : t -> t -> unit

Assigns to wire.

Sourceval assign : t -> t -> unit

Combinational Logic

The main combinational logic API for creating things like adders, multiplexers etc. This API is the same as provided by Bits.t.

By default Hardcaml performs constant propogation over signals - operations with purely constant values (and some other simple cases such as a &: vdd) will be simplified. You can avoid this by using the operations from the Unoptimized module.

Combinational logic API with constant propogation optimizations.

include Comb.S with type t := t
Sourceval sexp_of_t : t -> Sexplib0.Sexp.t
include Base.Equal.S__local with type t := t
Sourceval vdd : t

logic 1

Sourceval gnd : t

logic 0

Sourceval of_constant : Constant.t -> t

create signal from a constant

Sourceval of_bit_string : string -> t

convert binary string to constant

Sourceval of_int_trunc : width:int -> int -> t

Convert integer to constant. Negative values are sign extended up to width. Input values which are larger or smaller than those representable in width bits are truncated.

Sourceval of_int32_trunc : width:int -> int32 -> t
Sourceval of_int64_trunc : width:int -> int64 -> t
Sourceval of_int : width:int -> int -> t

Same as of_int_trunc

  • deprecated [since 2024-11] use [of_int_trunc]
Sourceval of_int32 : width:int -> int32 -> t
  • deprecated [since 2024-11] use [of_int32_trunc]
Sourceval of_int64 : width:int -> int64 -> t
  • deprecated [since 2024-11] use [of_int64_trunc]
Sourceval of_unsigned_int : width:int -> int -> t

Convert non-negative values to constant. Input values which are not representable in width bits will raise.

Sourceval of_unsigned_int32 : width:int -> int32 -> t
Sourceval of_unsigned_int64 : width:int -> int64 -> t
Sourceval of_unsigned_bigint : width:int -> Bigint.t -> t
Sourceval of_signed_int : width:int -> int -> t

Convert signed values to constant. Input values which are not representable in width bits will raise.

Sourceval of_signed_int32 : width:int -> int32 -> t
Sourceval of_signed_int64 : width:int -> int64 -> t
Sourceval of_signed_bigint : width:int -> Bigint.t -> t
Sourceval of_hex : ?signedness:Signedness.t -> width:int -> string -> t

convert hex string to a constant. If the target width is greater than the hex length and signedness is Signed then the result is sign extended. Otherwise the result is zero padded.

Sourceval of_octal : ?signedness:Signedness.t -> width:int -> string -> t

convert octal string to a constant. If the target width is greater than the octal length and signedness is Signed then the result is sign extended. Otherwise the result is zero padded.

Sourceval of_bigint_trunc : width:int -> Bigint.t -> t

Convert an arbitrarily wide integer value to a constant.

Sourceval of_string : string -> t

convert verilog style or binary string to constant

Sourceval of_bit_list : int list -> t

convert IntbitsList to constant

Sourceval of_decimal_string : width:int -> string -> t
Sourceval of_char : char -> t

convert a char to an 8 bit constant

Sourceval of_bool : bool -> t

convert a bool to vdd or gnd

Sourceval of_ascii_string_lsb : string -> t

convert a string to a series of 8-bit characters and concatenate them into a signal, with the first character of the string being in the least-significant bits

Sourceval of_ascii_string_msb : string -> t

convert a string to a series of 8-bit characters and concatenate them into a signal, with the first character of the string being in the most-significant bits

Sourceval random : width:int -> t

create random constant vector of given width

Sourceval zero : int -> t

zero w makes a the zero valued constant of width w

Sourceval ones : int -> t

ones w makes a constant of all ones of width w

Sourceval one : int -> t

one w makes a one valued constant of width w

Sourceval empty : t

the empty signal

Sourceval is_empty : t -> bool

returns true if the signal is empty

Sourceval (--) : loc:lexing_position -> t -> string -> t

names a signal

let a = a -- "a" in ...

signals may have multiple names.

Sourceval width : t -> int

returns the width (number of bits) of a signal.

let w = width s in ...

Sourceval address_bits_for : int -> int

addess_bits_for num_elements returns the address width required to index num_elements.

It is the same as Int.ceil_log2, except it wll return a minimum value of 1 (since you cannot have 0 width vectors). Raises if num_elements is < 0.

Sourceval num_bits_to_represent : int -> int

num_bits_to_represent x returns the number of bits required to represent the number x, which should be >= 0.

Sourceval to_constant : t -> Constant.t

convert the signal to a constant

Sourcemodule type For_collection = sig ... end
Sourceval concat_msb : t list -> t

concat_msb ts concatenates a list of signals - the msb of the head of the list will become the msb of the result.

let c = concat_msb [ a; b; c ] in ...

concat_msb raises if ts is empty or if any t in ts is empty.

Sourceval concat_lsb : t list -> t

Similar to concat_msb except the lsb of the head of the list will become the lsb of the result.

Sourceval split_lsb : ?exact:bool -> part_width:int -> t -> t list

Split signal into a list of signals with width equal to part_width. The least significant bits are at the head of the returned list. If exact is true the input signal width must be exactly divisable by part_width. When exact is false and the input signal width is not exactly divisible by part_width, the last element will contains residual bits.

eg:

  split_lsb ~part_width:4 16b0001_0010_0011_0100 =
    [ 4b0100; 4b0011; 4b0010; 4b0001 ]

  split_lsb ~exact:false ~part_width:4 17b11_0001_0010_0011_0100 =
    [ 4b0100; 4b0011; 4b0010; 4b0001; 2b11 ]
Sourceval split_msb : ?exact:bool -> part_width:int -> t -> t list

Like split_lsb except the most significant bits are at the head of the returned list. Residual bits when exact is false goes to the last element of the list, so in the general case split_lsb is not necessarily equivalent to split_msb |> List.rev.

Sourceval mux : t -> t list -> t

multiplexer.

let m = mux sel inputs in ...

Given l = List.length inputs and w = width sel the following conditions must hold:

l <= Int.pow 2 w, l >= 1

If l < Int.pow 2 w, the last input is repeated.

All inputs provided must have the same width, which will in turn be equal to the width of m.

Sourceval mux_strict : t -> t list -> t

Same as mux except requires:

l = Int.pow 2 w

Sourcemodule For_array : For_collection with type 'a collection := 'a array
Sourcemodule For_iarray : For_collection with type 'a collection := 'a iarray
Sourceval (@:) : t -> t -> t

concatenate two signals.

let c = a @: b in ...

equivalent to concat [ a; b ]

Sourceval is_vdd : t -> bool
  • deprecated [since 2025-03] use [to_bool]
Sourceval is_gnd : t -> bool
  • deprecated [since 2025-03] use [not to_bool]
Sourceval select : t -> high:int -> low:int -> t

select t ~high ~low selects from t bits in the range high...low, inclusive. select raises unless high and low fall within 0 .. width t - 1 and high >= lo.

Sourceval bit : t -> pos:int -> t

select a single bit

Sourceval msb : t -> t

get most significant bit

Sourceval lsbs : t -> t

get least significant bits

Sourceval lsb : t -> t

get least significant bit

Sourceval msbs : t -> t

get most significant bits

Sourceval drop_bottom : t -> width:int -> t

drop_bottom s ~width drop bottom width bits of s

Sourceval drop_top : t -> width:int -> t

drop_top s ~width drop top width bits of s

Sourceval sel_bottom : t -> width:int -> t

sel_bottom s ~width select bottom width bits of s

Sourceval sel_top : t -> width:int -> t

sel_top s ~width select top width bits of s

Sourceval (.:[]) : t -> (int * int) -> t

x.:[hi, lo] == select x hi lo

Sourceval (.:+[]) : t -> (int * int option) -> t

x.:+[lo, width] == select x (lo + width - 1) lo. If width is None it selects all remaining msbs of the vector ie x.:+[lo,None] == drop_bottom x lo

Sourceval (.:-[]) : t -> (int option * int) -> t

x.:-[hi, width] == select x hi (hi - width + 1). If hi is None it defaults to the msb of the vector ie x.:-[None, width] == sel_top x width

Sourceval (.:()) : t -> int -> t

x.(i) == bit x i

Sourceval insert : into:t -> t -> at_offset:int -> t

insert ~into:t x ~at_offset insert x into t at given offet

Sourceval mux2 : t -> t -> t -> t

mux2 c t f 2 input multiplexer. Selects t if c is high otherwise f.

t and f must have same width and c must be 1 bit.

Equivalent to mux c [f; t]

Sourceval mux_init : t -> int -> f:(int -> t) -> t
Sourceval cases : default:t -> t -> (t * t) list -> t

cases ~default select [(match0, value0); (match0, value0)...] compares select with matchN and outputs valueN. If nothing matches default is output. This construct maps to a case statement.

The matchN values must be constants.

Sourceval (&:) : t -> t -> t

logical and

Sourceval (&:.) : t -> int -> t
Sourceval (&+.) : t -> int -> t
Sourceval (&&:) : t -> t -> t

a <>:. 0 &: b <>:. 0

Sourceval (|:) : t -> t -> t

logical or

Sourceval (|:.) : t -> int -> t
Sourceval (|+.) : t -> int -> t
Sourceval (||:) : t -> t -> t
 a <>:. 0 |: b <>:. 0
Sourceval (^:) : t -> t -> t

logic xor

Sourceval (^:.) : t -> int -> t
Sourceval (^+.) : t -> int -> t
Sourceval (~:) : t -> t

logical not

Sourceval (+:) : t -> t -> t

addition

Sourceval (+:.) : t -> int -> t
Sourceval (++.) : t -> int -> t
Sourceval (-:) : t -> t -> t

subtraction

Sourceval (-:.) : t -> int -> t
Sourceval (-+.) : t -> int -> t
Sourceval negate : t -> t

negation

Sourceval (*:) : t -> t -> t

unsigned multiplication

Sourceval (*+) : t -> t -> t

signed multiplication

Sourceval (==:) : t -> t -> t

equality

Sourceval (==:.) : t -> int -> t
Sourceval (==+.) : t -> int -> t
Sourceval (<>:) : t -> t -> t

inequality

Sourceval (<>:.) : t -> int -> t
Sourceval (<>+.) : t -> int -> t
Sourceval (<:) : t -> t -> t

less than

Sourceval (<:.) : t -> int -> t
Sourceval lt : t -> t -> t
Sourceval (>:) : t -> t -> t

greater than

Sourceval (>:.) : t -> int -> t
Sourceval (<=:) : t -> t -> t

less than or equal to

Sourceval (<=:.) : t -> int -> t
Sourceval (>=:) : t -> t -> t

greater than or equal to

Sourceval (>=:.) : t -> int -> t
Sourceval (<+) : t -> t -> t

signed less than

Sourceval (<+.) : t -> int -> t
Sourceval (>+) : t -> t -> t

signed greater than

Sourceval (>+.) : t -> int -> t
Sourceval (<=+) : t -> t -> t

signed less than or equal to

Sourceval (<=+.) : t -> int -> t
Sourceval (>=+) : t -> t -> t

signed greated than or equal to

Sourceval (>=+.) : t -> int -> t
Sourceval (-->:) : t -> t -> t

Propositional logic implication operator

Sourceval to_string : t -> string

create string from signal

Sourceval to_int_trunc : t -> int

to_int t treats t as unsigned and resizes it to fit exactly within an OCaml Int.t.

  • If width t > Int.num_bits then the upper bits are truncated.
  • If width t >= Int.num_bits and bit t (Int.num_bits-1) = vdd (i.e. the msb of the resulting Int.t is set), then the result is negative.
  • If t is Signal.t and not a constant value, an exception is raised.
Sourceval to_int32_trunc : t -> int32
Sourceval to_int64_trunc : t -> int64
Sourceval to_int : t -> int

Same as to_int_trunc.

  • deprecated [since 2024-11] use [to_int_trunc]
Sourceval to_int32 : t -> int32
  • deprecated [since 2024-11] use [to_int32_trunc]
Sourceval to_int64 : t -> int64
  • deprecated [since 2024-11] use [to_int64_trunc]
Sourceval to_signed_int : t -> int

to_signed_int t treats t as signed and resizes it to fit exactly within an OCaml Int.t.

  • An exception is raised if the value cannot fit in the resulting int.
  • If t is Signal.t and not a constant value, an exception is raised.
Sourceval to_signed_int32 : t -> int32
Sourceval to_signed_int64 : t -> int64
Sourceval to_unsigned_int : t -> int

to_unsigned_int t treats t as unsigned and resizes it to fit exactly within an OCaml Int.t.

  • An exception is raised if the value cannot fit in the resulting int.
  • The value int value must be unsigned (so the max width is Int.num_bits - 1).
  • If t is Signal.t and not a constant value, an exception is raised.
Sourceval to_unsigned_int32 : t -> int32
Sourceval to_unsigned_int64 : t -> int64
Sourceval to_bool : t -> bool

Convert signal to a bool. The signal must be 1 bit wide.

Sourceval to_char : t -> char

Convert signal to a char. The signal must be 8 bits wide.

Sourceval to_ascii_string_lsb : t -> string

Convert into a string, with the first character being from the least-significant bits of the signal. The signal width must be a multiple of 8 bits.

Sourceval to_ascii_string_msb : t -> string

Convert into a string, with the first character being from the most-significant bits of the signal. The signal width must be a multiple of 8 bits.

Sourceval to_bstr : t -> string

create binary string from signal

Sourceval to_bigint : t -> signedness:Signedness.t -> Bigint.t

Convert bits to a Zarith.t

Sourceval bits_msb : t -> t list

convert signal to a list of bits with msb at head of list

Sourceval bits_lsb : t -> t list

convert signal to a list of bits with lsb at head of list

Sourceval repeat : t -> count:int -> t

repeat signal count times

Sourceval split_in_half_msb : ?msbs:int -> t -> t * t

Split signal in half. The most significant bits will be in the left half of the returned tuple.

  • If msbs is not provided, the signal will be split in half with the MSB part possibly containing one more bit.
  • If msbs is provided, msbs most significant bits will be split off.
Sourceval split_in_half_lsb : ?lsbs:int -> t -> t * t

Same as split_in_half_msb, but

  • If lsbs is not provided, the LSB part might have one more bit.
  • If lsbs is provided, lsbs least significant bits will be split off.

The most significant bits will still be in the left half of the tuple.

Sourceval bswap : t -> t
Sourceval sll : t -> by:int -> t

shift left logical

Sourceval srl : t -> by:int -> t

shift right logical

Sourceval sra : t -> by:int -> t

shift right arithmetic

Sourceval rotl : t -> by:int -> t

rotate left

Sourceval rotr : t -> by:int -> t

rotate right

Sourceval log_shift : f:(t -> by:int -> t) -> t -> by:t -> t

shift by variable amount

Sourceval uresize : t -> width:int -> t

uresize t ~width:w returns the unsigned resize of t to width w. If w = width t, this is a no-op. If w < width t, this selects the w low bits of t. If w > width t, this extends t with zero (w - width t).

Sourceval sresize : t -> width:int -> t

sresize t ~width:w returns the signed resize of t to width w. If w = width t, this is a no-op. If w < width t, this selects the w low bits of t. If w > width t, this extends t with w - width t copies of msb t.

Sourceval uextend : t -> width:int -> t

uextend t ~width:w behaves similarly to uresize t ~width:w but asserts that w >= width to prevent inadvertently chopping the signal.

Sourceval sextend : t -> width:int -> t

sextend t ~width:w behaves similarly to sresize t ~width:w but asserts that w >= width to prevent inadvertently chopping the signal.

Sourceval ue : t -> t

unsigned resize by +1 bit

Sourceval se : t -> t

signed resize by +1 bit

Sourceval resize_list : resize:(t -> int -> t) -> t list -> t list

resize_list ~resize l finds the maximum width in l and applies resize el max to each element.

Sourceval resize_op2 : resize:(t -> int -> t) -> (t -> t -> t) -> t -> t -> t

resize_op2 ~resize f a b applies resize x w to a and b where w is the maximum of their widths. It then returns f a b

Sourceval reduce : f:('a -> 'a -> 'a) -> 'a list -> 'a

fold 'op' though list

Sourceval reverse : t -> t

reverse bits

Sourceval mod_counter : max:int -> t -> t

mod_counter max t is if t = max then 0 else (t + 1), and can be used to count from 0 to max then from zero again. If max == (1<<n - 1), then a comparator is not generated and overflow arithmetic is used instead.

Sourceval compute_arity : steps:int -> int -> int

compute_arity ~steps num_values computes the tree arity required to reduce num_values in steps. steps<=0 raises.

Sourceval compute_tree_branches : steps:int -> int -> int list

compute_tree_branches ~steps num_values returns a list of length steps of branching factors required to reduce num_values. This tends to produce a slightly more balanced sequence than just applying compute_arity at every step.

Sourceval tree : arity:int -> f:('a list -> 'a) -> 'a list -> 'a

tree ~arity ~f input creates a tree of operations. The arity of the operator is configurable. tree raises if input = [].

Sourceval priority_select : ?branching_factor:int -> (t, t) Hardcaml_kernel__.Comb_intf.with_valid2 list -> (t, t) Hardcaml_kernel__.Comb_intf.with_valid2

priority_select cases returns the value associated with the first case whose valid signal is high. valid will be set low in the returned with_valid if no case is selected.

Sourceval priority_select_with_default : ?branching_factor:int -> (t, t) Hardcaml_kernel__.Comb_intf.with_valid2 list -> default:t -> t

Same as priority_select except returns default if no case matches.

Sourceval onehot_select : ?branching_factor:int -> (t, t) Hardcaml_kernel__.Comb_intf.with_valid2 list -> t

Select a case where one and only one valid signal is enabled. If more than one case is valid then the return value is undefined. If no cases are valid, 0 is returned by the current implementation, though this should not be relied upon.

Sourceval popcount : ?branching_factor:int -> t -> t

popcount t returns the number of bits set in t.

Sourceval binary_to_byte_qualifier : num_bytes:int -> t -> t

binary_to_byte_qualifier ~num_bytes t returns a byte qualifier encoding of a binary size for use when encoding contiguous byte enables or byte keep signals.

Sourceval is_pow2 : ?branching_factor:int -> t -> t

is_pow2 t returns a bit to indicate if t is a power of 2.

Sourceval leading_ones : ?branching_factor:int -> t -> t

leading_ones t returns the number of consecutive 1s from the most significant bit of t down.

Sourceval trailing_ones : ?branching_factor:int -> t -> t

trailing_ones t returns the number of consecutive 1s from the least significant bit of t up.

Sourceval leading_zeros : ?branching_factor:int -> t -> t

leading_zeros t returns the number of consecutive 0s from the most significant bit of t down.

Sourceval trailing_zeros : ?branching_factor:int -> t -> t

trailing_zeros t returns the number of consecutive 0s from the least significant bit of t up.

Sourceval floor_log2 : ?branching_factor:int -> t -> (t, t) Hardcaml_kernel__.Comb_intf.with_valid2

floor_log2 x returns the floor of log-base-2 of x. x is treated as unsigned and an error is indicated by valid = gnd in the return value if x = 0.

Sourceval ceil_log2 : ?branching_factor:int -> t -> (t, t) Hardcaml_kernel__.Comb_intf.with_valid2

ceil_log2 x returns the ceiling of log-base-2 of x. x is treated as unsigned and an error is indicated by valid = gnd in the return value if x = 0.

Sourceval binary_to_onehot : t -> t

convert binary to onehot

Sourceval onehot_to_binary : t -> t

convert onehot to binary

Sourceval binary_to_gray : t -> t

convert binary to gray code

Sourceval gray_to_binary : t -> t

convert gray code to binary

Sourceval gray_increment : t -> by:int -> t

Increment a gray code value. The implementation converts to binary, increments the binary value, then converts back to gray code.

Sourceval any_bit_set : t -> t

any_bit_set t returns vdd if at least one bit if set in t and gnd otherwise.

Sourceval all_bits_set : t -> t

all_bits_set t returns vdd if all bits in t are set and gnd otherwise.

Sourceval no_bits_set : t -> t

no_bits_set t returns vdd if no bits in t are set and gnd otherwise.

Sourceval incr : ?by:int -> t -> t

Increment (defaults to 1). Wrap on overflow.

Sourceval decr : ?by:int -> t -> t

Decrement (defaults to 1). Wrap on overflow.

Sourcemodule With_zero_width : sig ... end

Concatention, selection and resizing functions for signals encoded as an option where None means zero width.

Sourcemodule type Typed_math = sig ... end

Unsigned vector operations (ie may operate on Bits.t or Signal.t directly).

Signed vector operations (ie may operate on Bits.t or Signal.t directly).

Sourceval type_equal_id : t Core.Type_equal.Id.t
Sourcemodule Unoptimized : Comb.S with type t := t

Combinational logic API without constant propogation optimizations.

Sourceval of_bits : Bits.t -> t

Create the signal from bits.

Sourceval to_bits : t -> Bits.t

Convert the signal to bits. Raises if the signal is not a constant.

Registers

Registers are configured using a Reg_spec.t. This encodes the clock, synchronous clear, and asychronous reset used.

Sourcemodule Reg_spec : Reg_spec.S with type signal := t
Sourcetype 'a with_register_spec = ?enable:t -> ?initialize_to:Bits.t -> ?reset_to:Bits.t -> ?clear:t -> ?clear_to:t -> Reg_spec.t -> 'a
Sourceval reg_fb : (width:int -> f:(t -> t) -> t) with_register_spec
Sourceval reg_fb_and_next : (width:int -> f:(t -> t) -> t * t) with_register_spec

Like reg_fb but returns both the registered value and the next cycle's value (i.e. the output of f prev_value). The next value ignores clear or reset if applied, i.e. if clear is applied, next will still be f prev_value rather than clear_to.

Sourceval pipeline : ?attributes:Rtl_attribute.t list -> (n:int -> t -> t) with_register_spec

Pipeline a signal n times with the given register specification. If set, a list of RTL attributes will also be applied to each register created.

Sourceval cut_through_reg : ?initialize_to:Bits.t -> ?reset_to:Bits.t -> ?clear:t -> ?clear_to:t -> Reg_spec.t -> enable:t -> t -> t

A register which forwards its input value to the output during cycles in which it is enabled.

Implemented as a register with a mux on the output. Note that the cut through bevahiour will also occur if enable is high during a clear (or even reset) operation.

Sourceval prev : (t -> (int -> t) Base.Staged.t) with_register_spec

Staged.unstage (prev spec ?enable d) returns a function prev n which provides d registered n times (ie the value of d n cycles in the past). n=0 means the current (combinational value).

The internal registers are shared between calls. When called multiple times with a maximum value of n exactly n registers are created.

Sourceval counter : ?enable:t -> ?initialize_to:Bits.t -> ?reset_to:Bits.t -> ?clear:t -> ?clear_to:t -> ?by:int -> Reg_spec.t -> width:int -> t

Basic counter. Adds by on each enabled cycle. Wraps on over/underflow.

Memories

multiport_memory provides the low-level primitive from which Hardcaml memories are created. It provides a memory with an arbitrary number of read and write ports that is asychronously read.

By default synthesizers will infer either LUT ram or register banks from this primitive.

Limiting the number of read/write ports and placing a register on the read address or read output port will allow synthesizers to infer single or simple dual port RAM from RTL. ram_rbw and ram_wbr are examples of this.

Sourceval multiport_memory : ?enable_modelling_features:bool -> ?verbose:bool -> ?name:string -> ?attributes:Rtl_attribute.t list -> ?initialize_to:Bits.t array -> int -> write_ports:t Write_port.t array -> read_addresses:t array -> t array

Synchronous write / asynchronous read memory. Supports an arbitrary number of read_addresses and write_ports. Placement of registers on the address or data output will allow synthesizers to infer RAMs from generated RTL (see also Ram.create which builds on this primitive to implement inferred memories).

Any provided attributes are applied to the memory array itself.

The memory may be initialized by providing initialize_to.

enable_modelling_features allows multibit enable and port scaling features. In both cases they will generate valid synthesizable RTL but backend tool inference is unlikely to work leading to sub-optimal designs.

In both cases extra read/write ports are generated and the internal RAM may be narrowed to support the feature.

For multibit enables the number of write enables must evenly divide the write data width or an exception will be raised.

For port scaling the read/write port ratio must be a power of two. It is specified by making the read and write address widths different and scaling the write data width appropriately. The size and initialize_to parameters are specified relative to the write port with the widest data bus.

Sourceval rom : read_addresses:t array -> Bits.t array -> t array

A multi-read port asynchronous ROM built from a memory primitive. This can be used to map ROMs into RAM resources by registering the output.

Sourceval memory : ?attributes:Rtl_attribute.t list -> int -> write_port:t Write_port.t -> read_address:t -> t
Sourceval ram_wbr : ?name:string -> ?attributes:Rtl_attribute.t list -> write_port:t Write_port.t -> read_port:t Read_port.t -> int -> t
Sourceval ram_rbw : ?name:string -> ?attributes:Rtl_attribute.t list -> write_port:t Write_port.t -> read_port:t Read_port.t -> int -> t

Signal representations

Operate on the underlying representation of the signal type. This is useful if you need to operate on the underlying Signal.Type that represents the Signal.S that you are working with or to reflect on the extra information attached to the specific Signal.S (like clock domains for Clocked.t).

Sourceval to_rep : t -> Hardcaml_kernel__.Signal__type.t * info

Return the underlying representation for the signal.

Sourceval from_rep : Hardcaml_kernel__.Signal__type.t -> info -> t

Construct a signal from the underlying representation and the information tracked by this signal.

Sourceval update_rep : t -> info:info -> t

Update the information attached to this signal.

Sourceval pp : Base.Formatter.t -> t -> unit

Pretty printer.

Sourceval validate_signals_are_consistent : op_name:string -> (string * t) list -> Clock_domain.Runtime.t

Check if the provided signals are consistent where the definition of consistency is defined by the underlying signal type.

For the unclocked Signal.t, this does nothing.

For the clocked signal, this asserts that all the provided signals have the same runtime domain and return the domain, raises if they're not compatible. ~op_name will be shown in the error message reporting a clock domain mismatch.

The rules of runtime clock domain consistencies are:

  • There cannot be any unknowns.
  • Amongst the non-constants, their clock domains must match.
  • Having only constants (or an empty list) is valid, in which case this function will just return a constant runtime clock domain.
Sourceval get_domain : t -> Clock_domain.Runtime.t

The elaboration-time runtime clock domain of the signal.

Sourceval ensure_domain : loc:lexing_position -> ?name:string -> t -> required_domain:Clock_domain.Runtime.t -> t

Validates that when required_domain is expected, dom t is able to satisfy that requirement.

  • When required_domain is a constant, dom t have to be a constant
  • When required_domain is Exact x, dom t can be either Exact x or Constant
  • When required_domain is Unknown, this check will always fail.
Sourceval unwrap_signal : loc:lexing_position -> t -> dom:Clock_domain.Runtime.t -> Signal.t

Return the base signal if the clocked representation has the given domain.

Sourceval to_clocked : Signal.t -> dom:Clock_domain.Runtime.t -> t

Creates a signal with the associated domain. Raises if the signal already has a domain attached to it.

Sourceval map : t -> f:(Signal.t -> Signal.t) -> t

Map over the base implementation, keeping the same info.

Sourcemodule Unsafe : sig ... end
Sourcemodule Overrides : sig ... end

Defines functions that shadow the standard Signal construct functions and ensure that a domain is provided.

Sourcemodule Expert : sig ... end