HDFS Design API

Building a hardware module in HDFS consists of constructing a cyclic abstract syntax tree using the Signal datatype. This datatype may then be processed in order to construct VHDL or Verilog netlists or perform simulation.

The following short example illustrates the basic process of hardware design in HDFS.

First we need to create the hardware design itself.

let some_hardware a (b:Signal) (c:Signal) =
  let d = regc enable (a + b) in
  (d <<< 1) - c + d.[0,0].mux2(2, a) 

The module is abstracted as a function which takes 3 signals, performs some (meaningless) operation on them, and returns 1 signal.

When called the function some_hardware will generate an abstract syntax tree representing the hardware. This can then be converted into a circuit datatype from which netlists can be written or simulation performed:

  let d = some_hardware (input "a" 2) (input "b" 2) (input "c" 2) in
  let circuit = Circuit.create [ d.output "d" ] in
  Circuit.write_file Verilog.write "output/" "test" ".v" circuit;
  Circuit.write_file Vhdl.write "output/" "test" ".vhd" circuit;
  let sim = Simulator.create circuit in
  ...

HDFS operators

Where possible standard F# operators are used in the API. F#, however, places some restrictions on the types of arguments that may be used. In these cases operators ending with a : (unsigned) or + (signed) are provided. Sometimes both versions are provided in order to allow overloading of the operators.

There is an issue with the API regarding operator overloading. ML style type inference and operator (and function) overloading are not easy bedfellows. Often in simple functions you may receive type errors. For example:

> let compare a b = a <: b;;

  let compare a b = a <: b;;
  ------------------^^^^^^^

stdin(8,18): error: FS0001: Type error in the use of the overloaded operator '(<: )'. The type 'int' does not support any operators named '<:' 
stopped due to error

> let compare (a:Signal) b = a <: b;;

  let compare (a:Signal) b = a <: b;;
  ---------------------------^^^^^^^

stdin(7,27): error: Could not resolve the ambiguity inherent in the use of the overloaded operator '( <: )' at or near this program point. Use type annotations to resolve the ambiguity.
stopped due to error

In these cases it is necessary to constrain the type of the overloaded argument.

> let compare a (b:Signal) = a <: b;;

val compare : Signal -> Signal -> Signal

Constants

Verilog style constants

Constants may written as strings using a style similar to verilog. For example,

"5'b01001"

specifies the a 5 bit constant with the value 9. The format of the string is

"<width>'<base><value>"

Base defines what characters the value may contain. If the value provided is larger than width then the result is truncated. If it is shorter then the value is either zero extended or sign extended depending on the control character used.

Some operators and functions are able to operate directly on strings in this style. In these cases the width is optional and if omitted will be inferred from the context.

Constant optimization

As signals are combined constant arguments are detected and will be used evaluate the result directly when possible. This implements a form of constant propagation optimization. Note that this optimization does not work with wires even if the argument is a constant.

This optimization is applied by default but may be disabled by setting Signal.constant_propogation to false ie

  constant_propogation := false;

Predefined constants and signals

Arithmetic

The binary operators are overloaded so that the right hand argument may be an integer or verilog style string. For addition and subtraction the right hand operand will be converted to a constant with the same width as the left operand. For multiplication the rules are more complex.

Bit manipulation

Shifting

The functions <<<, >>>, sll, srl and sra take an integer argument to shift by.

shift_right_logical, shift_left and shift_right_arithmetic take a signal argument to shift by. They are built using a log shift circuit.

The operators <<:, >>: and >>+ are overloaded and take an integer or signal to shift by.

The barrel shifters both take a signal argument to shift by.

Muxing

Bitwise logical

1. ||| is the operator version of bor. It is not placed in the table as it conflicts with the wiki markup syntax.

The overloaded logical operators may take a signal, integer or string as the right hand argument.

Comparison

All comparison operators are overloaded to take an integer or string as the right hand argument.

In all cases both operands must the same width and the returned result is 1 bit wide.

Sequential elements

The type of register built may be controlled by substituting the empty signal for the reset, reset_value and enable signals. The follow table describes what happens in each case.

Instantiation

Generics

Generics for instantiations are described using a tuple with the following syntax

string * GenericSpec * (GenericData option)  

The string is the name of the generic. GenericSpec describes the type of the generic and an optional default value. GenericData describes the optional value of the generic when the component is instantiated.

This specification of a generic value follows the VHDL style of specifying generics with a default value on component declarations.

The GenericSpec is defined as follows:

type GenericSpec = 
  | Gd_Bit of int option
  | Gd_Bv of int * int * string option
  | Gd_Sl of int option
  | Gd_Slv of int * int * string option
  | Gd_Int of int option
  | Gd_Nat of int option
  | Gd_Pos of int option
  | Gd_Float of float option
  | Gd_Time of string option
  | Gd_String of string option
  | Gd_Bool of bool option

For example,

   Gd_Slv(3,0,Some("1100"))

GenericData is defined as follows:

type GenericData = 
  | G_Bit of int 
  | G_Vec of string
  | G_Int of int 
  | G_String of string
  | G_Float of float
  | G_Bool of bool

A complete generic specification would look like this:

("the_generic", Gd_Slv(3,0,Some("1100")), Some(G_Vec("0011")))

and would lead to the following VHDL code:

 component ...
  generic (
   the_generic : std_logic_vector(3 downto 0) := "1100";
   ...
 begin
  ...

  the_black_box: black_box  
    generic map (
      the_generic => "0011",
    ...

Care must be taken when a black box is instantiated multiple times. The GenericSpec on each instantiation should be the same or the default value used may not be the one expected. Further, not all generic types are valid in both VHDL and Verilog. In general, when not importing a library such as the supplied Xilinx Unisim binding, generics in this form should probably be used.

("the_generic", Gd_Slv(3,0,None), Some(G_Vec("0011")))
("the_generic", Gd_Int(None), Some(G_Int(3)))

Misc

Behavioral code

Behavioral code allows the description of hardware using guarded assignments. This style is similar to the coding of processes, in VHDL, or always blocks, in Verilog.

Unlike VHDL or Verilog statements in behavioral code are just elements of the abstract syntax tree and may therefore be manipulated programmatically.

Code consists of lists of assignments, if and case statements. To connect the code into a circuit the behave function is used. Here's short example.

  let r = b_regc enable 8 in
  let w = b_wire0 4 in
  behave [
    b_if (c ==: 3) [
      r $== c + 4;
    ] [
      r $== c - 4;
    ];
    b_switch (c) [
      b_case (consti 3 0) [ w $== r.q ];
      b_case (consti 3 1) [ w $== 1 ];
      b_case (consti 3 2) [ w $== 3 ];
    ]
  ]

Assignments in behavioral code can be made to registers or wires and may be freely intermixed. If no assignment is made to a register during a clock cycle it's previous values is held. If no assignment is made to a wire then it is driven to a default value specified on construction of the wire (this avoids any possibility of inferring latches).

The following functions create special nodes (called BehaveAssignTarget's) to which behavioral assignments are made.

The following functions are used within behave code blocks to define functionality.