Module Design

module Design: sig .. end

Digital design entry.

Contents

Enhanced features compared to HDCaml 0.2.9
Circuit Types
Circuit Data <-- Start here for actual design entry functions/operators
Signal Assignment and Annotation
Width Utilities
Top Level Ports
Constants
Bit Manipulation
Bitwise Logicals
Arithmetics
Shifting
Comparisons
Muxing
Registers

Enhanced features compared to HDCaml 0.2.9

This release enhances the design entry module of HDCaml 0.2.9 with the following features:

strict error checking
possibility to deactivate strict checks for a subset of functions/operators
possibility to exactly locate errors in the source code
debugging support (find names and nodes) with exact localisation in source
renaming of illegal/duplicate identifiers (names) for input, output, signal, --, start_circuit and circuit.
additional warnings concerning possibly unwanted combinations of arguments to functions/operators
detecting combinational loops during assignment of dangling signals with the <== operator.
checking for unconnected dangling signals (which count as errors because they can be the reason for defective Verilog code)
listing unused inputs
listing unused circuit nodes in general
checking for balanced use of structuring functions like start_circuit/get_circuit and circuit/endcircuit
design entry functions and operators (including get_circuit) must not be used before start_circuit

Instructions: Compile & Run

This release introduces a workaround which enables localization of HDCaml errors by source-code line numbers. It works by raising an uncaught exception, which causes display of a stack trace. This way one HDCaml error per compilation can be conveniently located. Compile and run your HDCaml program as shown below to make it work:

ocamlc -g -o example_circuit.exe hdcaml.cma example_circuit.ml

ocamlrun -b example_circuit.exe

(Option -g of ocamlc causes the executable to contain debug info which is needed for the next command. Option -b of ocamlrun causes the run time system to print a stack trace when an uncaught exception occurs.)

Check Rules

Any function or operator can check for different error or info conditions which are documented as part of the description of each function/operator. There are a couple of common principles, though, which apply to every function/operator:

Error conditions:

The empty signal is not allowed as an argument to any function or operator which takes type signal as a parameter. (#)
No function or operator returns an empty signal, i.e. arguments which would cause an empty signal to be returned are considered erroneous. (#)
Empty Strings ("") are not allowed for signal/circuit/port names (exception: anonymous signals: see Design.signal).
Correct bitwidth of signal operands is enforced at operator call (see operator description for details).
Structuring functions like start_circuit/get_circuit and circuit/endcircuit must be balanced, i.e. no opening function without closing one and vice versa.
Negative numbers are no valid argument to any function or operator.
The number 0 is no valid argument to any function or operator except for indices and shift-amounts. (#)
Indices of a signal with width N have to be in the range 0...(N-1).

Note: error conditions 1., 2. and 7. (marked with (#)) are not used for functions/operators of class 2 (see definition below in subsection Configure Strict Checks) when set_strict_checks is set to false.

Info conditions:

Using the same signal twice as arguments for one function or operator might be unwanted and issues an info in most cases (exception: multiplications).
Duplicate names get renamed during design entry. This is reported for every renamed signal.

Renaming

HDCaml 0.2.10 allows only names which are legal in all of its output languages: Verilog, VHDL, C (C++, SystemC). This boils down to the following rules:

legal names contain only letters (a-z, A-Z), digits (0-9) and the underscore (_)
legal names start with a letter
names are case sensitive

Due to the nature of identifiers/names in HDCaml (strings) they can contain illegal characters or can be used multiple times without the OCaml compiler being able to detect such wrong use. Therefore the HDCaml library must take care of this issue. HDCaml doesn't produce error messages and doesn't stop the program in case of illegal names used, but tries to modify them so that they become legal. This procedure is called renaming in this documentation. The user can get the behavior of conventional compilers (i.e. illegal names cause errors) by setting raise_exception_at_info true.

In Version 0.2.10 the renaming was moved completely into the module at hand (Design) and it gives the user exact reasons for why certain names are not acceptable and how they get renamed.

There are reasons to rename identifiers although they are legal in terms of the rules above. These are:

they are identical to keywords of generated languages
they are identical to implicitly generated signals of HDCaml (clock, reset, vdd, gnd, high, low)
they are used multiple times
they contain illegal substrings:
- name ends with the rename suffix (_renamed), immediately followed by a number, e.g. x_renamed15
- name contains the subcircuit delimiter (double underscore), e.g. x__y
- name consists of the node prefix (n_) immediately followed by a number, e.g. n_1

The new names are (roughly) calculated in this way:

Illegal characters and substrings are deleted from the name.
If nothing of the original name remains, start from the scratch with the new name sig (if there are more of these completely illegal names, this results in names of the form sig_renamed<n> later on).
The new name is compared to language keywords. (#)
The new name is prepended with the current subcircuit prefix.
The new name (plus subcircuit prefix) is compared to previously used identifiers and language keywords.
If one of those matches or the result of step 3 was positive, the new identifier gets the suffix _renamed plus a consecutive number. In case the original identifier ended with _renamed<n>, this is removed prior to the operation.

(#) The reason for step 3 is that signal names are used as struct members without subcircuit prefix in SystemC. Example: the name "if" of a signal in subcircuit "x", which would be a legal name ("x__if") in VHDL and Verilog would nevertheless create an error in the generated C code, where "if" would be used as a member name of the struct "x".

Configure Strict Checks

Concerning strictness of error checks, the functions and operators of HDCaml can be divided into two classes:

functions/operators where strict checks are absolutely useful
functions/operators where strict checks may be useful or not, depending on the requirements and programming habits of the user

Functions/operators of class 1 are:

start_circuit, get_circuit, circuit, endcircuit
signal, <==, --
input, output
one, bit, msb, lsb
all logical operators: ~:, &:, ^:, |:
all arithmetic operators: +:, -:, *:, *+
all comparisons: ==:, /=:, <:, >:, <=:, >=:, <+, >+, <=+, >=+
all shifts: <<:, <<+, >>:, >>+
mux2, mux
reg

Functions/operators of class 2 are:

const, zero, ones
select, ++, concat, repeat, msbs, lsbs, split, bits

(The constants empty, vdd, gnd, high and low don't belong to any of the two classes.)

The functions/operators of class 2 are often used to build signals recursively, like it is usual in functional languages with lists. The following similarities can be observed (left side: functional languages, right side: HDCaml functions/operators):

list <-> signal
[] <-> empty
:: <-> ++
List.hd <-> msb or lsb (only defined for list/signal <> []/empty; msb and lsb belong to class 1 therefore)
List.tl <-> lsbs or msbs

Other functions/operators of class 2 can be defined in such a way, that they return empty for corner cases, which can also be useful in generally describing a circuit:

const ""
zero 0
ones 0
select signal msb lsb with msb < lsb (not very intuitive but status quo)
concat []
repeat signal 0
split signal with width signal < 2 (returns a pair where one or both elements can be empty)
bits empty (returns [])

Functions/operators of class 2 can add expressive power to HDCaml when used carefully. But they can also cause subsequent errors, which are harder to detect in case of unthoughtful use. To reflect this properties, there is a switch that allows the user to turn checks for class 2 on and off.

You can find additional descriptions of differences between the two modes further below, at the documentation of the respective functions/operators. These are of the form: "(strict: limitations when set_strict_checks true; ; else: limitations when set_strict_checks false;)".

val set_strict_checks : bool -> unit

Switch to turn the strict checks on and off for functions/operators of class 2 (see definition above).

The default setting is true, i.e. strict checks are active for all functions/operators, including those of class 2. This default was chosen to provide HDCaml beginners with more useful error messages at the start.

Experienced HDCaml users can turn the switch off to enable additional expressive power of HDCaml. This may also be useful to make old HDCaml programs compatible with 0.2.10 in an easy way.

You can even have both benefits (more useful checks and more expressive power), although not at the very same time. But you can set strict checks on and off for single functions or parts of your HDCaml program like this:

  ...
  set_strict_checks false;
  some_tricky_recursive_function x y z ;
  set_strict_checks true;
  ...

There is no recommended setting of that switch that fits the needs of all users. Just be aware, that you will get potentially less useful error messages if you disable strict checks.

set_strict_checks true; ... strict checks are turned on for class 2 (default behavior).

set_strict_checks false; ... strict checks are turned off for class 2.

val get_setting_strict_checks : unit -> bool

Returns current setting of switch above.

Configure Error Reporting

There is a number of new functions in this release which allow the user to specify the behavior of the error reporting. These functions need only be called if the default behavior should be changed. Therefore old HDCaml designs are fully compatible.

There are two kinds of messages: errors and infos. An error denotes a critical problem in the source code and leads to a termination of the program via an uncaught exception. An info is a message the user might be interested in. The program continues to run after an info. (This is the default behavior which can be changed for both kinds of messages.)

Default behavior (when switches are not used):

infos don't raise exceptions
errors raise exceptions

val raise_exception_at_info : bool -> unit

Causes an info to have the same consequences as an error, i.e. it raises an exception. This switch can be used to find the context of an info message and must be set to true to make optimal use of find_name and find_node.

raise_exception_at_info true; ... next info will terminate program.

raise_exception_at_info false; ... program will continue to run after an info (default behavior).

val get_setting_exception_at_info : unit -> bool

Returns current setting of switch above.

val raise_exception_at_error : bool -> unit

Allows to inhibit the raising of an exception after occurrence of an error, that means the program is further executed. This allows to see subsequent messages during one run but produces potentially defective Verilog or SystemC files. Do not enable this switch unless you know exactly what you do!

raise_exception_at_error true; ... raises exception after error (default behavior).

raise_exception_at_error false; ... no exception; program continues to run.

val get_setting_exception_at_error : unit -> bool

Returns current setting of switch above.

These functions can be used repeatedly at any position in the HDCaml program. E.g. exceptions for infos could be turned on only during a single function call:

  ...
  raise_exception_at_info true;
  some_function a b c ;
  raise_exception_at_info false;
  ...

The same is true for the other configuration functions.

Trace Names and Nodes

val find_name : string -> unit

Creates an info output when the given name is being used in signal, -- (annotation), input, output, start_circuit or circuit (start of subcircuit).

Together with the lists of unconnected signals and unused inputs (which are displayed when get_circuit is called) and raise_exception_at_info true this can be used to track down one unconnected dangling signal or unused input per run (plus one initial run to get the list). The function can be used to find any name, by the way, not only unconnected signals or unused inputs.

Example: find_name "subcircuit__mysignal";

Note: signal names, annotated names and subcircuit names may include a subcircuit prefix of the form "subcircuit__" (subcircuit name plus double underscore) if they are used inside of a subcircuit. Inputs and outputs don't get such prefixes.

This function might seem pointless because the user knows when he uses which name. There are situations, however, that make tracing of names tedious or even impossible:

items get renamed because of multiple use of the same name
names are created dynamically
the same name (annotation, signal) occurs in multiple different subcircuits
anonymous signals (signal "" width) are used, see Design.signal

In these cases this function might come in handy.

This function can be used at any position in the HDCaml program. Only the trace for the last name ("name2" in this example) will be active if you use it repeatedly, like:

  ...
  find_name "name1";
  find_name "name2";
  ...

The empty string as an argument (i.e. find_name "";) turns name tracing off. This has the same effect as not using this function at all.

val find_node : int -> unit

Creates an info output when the given node number is being generated.

Together with the list of unused nodes (which is displayed when get_circuit is called) and raise_exception_at_info true this can be used to track down one unused node per run (plus one initial run to get the list).

The OCaml compiler is sometimes helpful in finding unused nodes, too, by reporting unused variables. But it doesn't find every unused node (as of version 3.09.3), for example in this code fragment (inp_list is used once, so ocamlc doesn't complain):

  ...
  let inp = input "name" 4 in
  let inp_list = bits inp in
  output "first_bit" (List.hd inp_list);
  ...

The function can be used to find any node, by the way, not only unused ones. Have you ever wondered, for example, which construct in your HDCaml program generates nodes like "n_17" in the Verilog or VHDL code? With this function you can simply look it up, like find_node 17;.

Attention: node numbers change when a HDCaml program is changed. So don't forget to turn find_node off after finding a certain node and changing the code, because otherwise you would find a completely different node which happens to get the same number afterwards.

This function can be used at any position in the HDCaml program. Only the trace for the last node (2 in this example) will be active if you use it repeatedly, like:

  ...
  find_node 1;
  find_node 2;
  ...

Zero as an argument (i.e. find_node 0;) turns node tracing off. This has the same effect as not using this function at all.

Circuit Types

type signal = Circuit.signal

Signals represent bit vectors.

type circuit = Circuit.circuit

A circuit is a completed circuit design.

Circuit Data

val start_circuit : string -> unit

Starts a new circuit design. Initializes the internal circuit database.

val get_circuit : unit -> circuit

Returns the circuit design and resets the internal database.

Checks for unused/unconnected elements and unbalanced use of circuit/endcircuit :

too few calls of endcircuit => error
unconnected dangling signals are left => error
unused inputs are left => info
unused circuit nodes are left => info

Every element can be searched for. Use find_name "name" for inputs, dangling signals and opening subcircuits (circuit), find_node number for circuit nodes.

val circuit : string -> unit

Creates a new subcircuit and namespace.

val endcircuit : unit -> unit

Closes a subcircuit. Issues an error if too few subcircuits have been opened.

Signal Assignment and Annotation

val signal : string -> int -> signal

signal name w. Creates a dangling signal, which may be assigned later.

Anonymous signals:

Passing an empty string as name (signal "" w) creates an "anonymous signal". This means that a name is being created automatically by HDCaml. The created name looks like that of other unnamed nodes, e.g. "n_15" for a anonymous signal which happens to get assigned the id 15 internally.

The use of anonymous signals is convenient in user written library functions which define sequential logic (i.e. registers with feedback and therefore dangling signals are used). In these cases the user no longer has to make up meaningful names.

val (<==) : signal -> signal -> unit

Assigns a value to a dangling signal.

It's an error if the assignment closes a combinational loop.

val (--) : string -> signal -> signal

Applies a label (name) to a signal.

Width Utilities

val width : signal -> int

Width of a signal.

The following functions check whether width constraints are fulfilled and raise the exception Design_error otherwise.

val check_width : int -> signal -> unit

Checks that a signal has a given width.

val check_width_bit : signal -> unit

Checks that a signal is a single bit.

val check_width_nonzero : signal -> unit

Checks that a signal has a nonzero width.

val check_width_same : signal -> signal -> unit

Checks that two signals have the same width.

Top Level Ports

val input : string -> int -> signal

Creates a top-level input.

val output : string -> signal -> unit

Assigns a top-level output.

Constants

Note: Result of const, zero, one and ones must be at least one bit wide.

val const : string -> signal

Creates a constant. const string; String must be 1's and 0's. (strict: string <> ""; else: string may be "")

val zero : int -> signal

Creates a constant 0. zero width; (strict: width>=1 ; else: width>=0)

val one : int -> signal

Creates a constant 1.

val ones : int -> signal

Creates a constant of 111's. ones width; (strict: width>=1 ; else: width>=0)

val empty : signal

An empty signal. (width = 0)

val vdd : signal

A single bit set to 1.

val gnd : signal

A single bit set to 0.

val high : signal

New in 0.2.10. A single bit set to 1.

val low : signal

New in 0.2.10. A single bit set to 0.

Bit Manipulation

val select : signal -> int -> int -> signal

Selects a section of a signal. LSB (right most) is indexed with 0. select signal msb lsb. (strict: msb>=lsb ; else: msb<lsb is allowed)

val bit : signal -> int -> signal

Selects an individual bit from a signal.

val (++) : signal -> signal -> signal

Concatenates two signals together. left ++ right (strict: only one side may be empty ; else: both sides may be empty)

val concat : signal list -> signal

New in 0.2.10. Concatenates a list of signals together. Head of list is MSB. List items may have different widths. (strict: list must not be [] and at least one item must have non-zero width; else: list may be [], all items may be empty )

val repeat : signal -> int -> signal

Repeats concatenation N times. repeat signal n; (strict: signal<>empty, n>=1; else: signal may be empty, n>=0)

val msb : signal -> signal

Selects the most significant bit (left most).

val msbs : signal -> signal

Selects all bits except the LSB. msbs a (strict: width a >= 2; else: width a >= 1)

val lsb : signal -> signal

Selects the least significant bit (right most).

val lsbs : signal -> signal

Selects all bits except the MSB. lsbs a (strict: width a >= 2; else: width a >= 1)

val split : signal -> signal * signal

Splits a signal into two equal parts. If signal has odd number of bits, left side will have one more bit than right. split a (strict: width a >= 2; else: no restrictions)

val bits : signal -> signal list

Splits a signal into a list of bits. MSB is head of list. (strict: width a >= 1; else: no restrictions)

Bitwise Logicals

Notes: (for all operators except (~:) )

Both signals must have the same width
An info is generated if both arguments are the same signal.

val (~:) : signal -> signal

Bitwise NOT.

val (&:) : signal -> signal -> signal

Bitwise AND.

val (^:) : signal -> signal -> signal

Bitwise XOR.

val (|:) : signal -> signal -> signal

Bitwise OR.

Arithmetics

Note: An info is generated if both arguments of addition or subtraction are the same signal. (This is not the case for multiplications.)

val (+:) : signal -> signal -> signal

Addition. All signals have same width, including the result.

val (-:) : signal -> signal -> signal

Subtraction. All signals have same width, including the result.

val (*:) : signal -> signal -> signal

Unsigned multiplication. a *: b. Width of result is (width a)+(width b).

val (*+) : signal -> signal -> signal

Signed multiplication. a *+ b. Width of result is (width a)+(width b).

Shifting

Notes: signal (shift-op) shift

shift must not be negative
An info is generated if shift=0 or shift >= width a.

val (<<:) : signal -> int -> signal

Unsigned shift left.

val (<<+) : signal -> int -> signal

New in 0.2.10. Signed shift left. (Just for completeness, identical to <<:. )

val (>>:) : signal -> int -> signal

Unsigned shift right.

val (>>+) : signal -> int -> signal

Signed shift right.

Comparisons

Notes:

Both signals must have the same width
An info is generated if both arguments are the same signal.

val (==:) : signal -> signal -> signal

Equal.

val (/=:) : signal -> signal -> signal

Not equal.

val (<:) : signal -> signal -> signal

Unsigned less than.

val (>:) : signal -> signal -> signal

Unsigned greater than.

val (<=:) : signal -> signal -> signal

Unsigned less than or equal.

val (>=:) : signal -> signal -> signal

Unsigned greater than or equal.

val (<+) : signal -> signal -> signal

Signed less than.

val (>+) : signal -> signal -> signal

Signed greater than.

val (<=+) : signal -> signal -> signal

Signed less than or equal.

val (>=+) : signal -> signal -> signal

Signed greater than or equal.

Muxing

val mux2 : signal -> signal -> signal -> signal

2-input mux: mux2 select on_high on_low. Width of select must be 1. Both signals (on_high, on_low) must have the same width.

An info is generated if both arguments (on_high, on_low) are the same signal.

val mux : signal -> signal list -> signal

N-Input Mux: mux ctrl items

The control input ctrl is binary encoded (a N bit wide control signal can select 2^N items). If ctrl has more bits than necessary, the most significant redundant bits are simply ignored. If the number of items is no power of 2, the last element is replicated to get a list of the correct length (e.g. if ctrl is 3 bits wide, but items only has 6 elements (2 missing), ctrl = 5 or 6 or 7 will all select the last item in your list).

Errors:

The list of signals (items) is empty.
Some elements of the list have different widths than others.
Input ctrl doesn't have enough bits to select all items.

Infos:

All items are the same signal
The number of items is no power of 2
The control input has more bits than necessary.

Registers

val reg : signal -> signal -> signal

An info is generated if both arguments (enable, data) are the same signal.