hoodlum (alpha)

Hoodlum is a nice-looking hardware description language that compiles to Verilog. It wants to add stronger type guarantees and high-level concepts like enums (and structs/typedefs), but also make FPGA design easier and more fun to get involved with. To get started:

cargo install hoodlum

Add this to a file called blinky.hdl:

entity Main {
    in clk: bit,
    out LED1: bit,
}

impl Main {
    def mut index: uint{..6000000};
    on clk.posedge {
        if index == 6000000 - 1 {
            index <= 0;
            LED1 <= !LED1;
        } else {
            index <= index + 1;
        }
    }
}

And run:

hoodlum blinky.hdl -o output.v

The tutorial and examples target the $20 iCEstick evaluation board and the IceStorm open source compiler toolchain. See "examples/blinky" for the complete source code.

NOTE: I'm learning Verilog and VHDL as I go along. Feel free to suggest ideas and best practices in the issues section!

Examples

• examples/blinky — Blink an LED on and off with a counter. Example for the iCEstick evaluation board.
• examples/sequence — Shows an LED display pattern compiled via a sequence generator.
• examples/ntsc — Generates NTSC video and displays a static image. Requires an external circuit.
• examples/ethernet — Drives the enc424j600 Ethernet PMOD board to send UDP packets. Requires an enc424j600 PMOD board.

Running on an iCEstick Evaluation Kit

Each example has a Makefile allowing you to run:

make && make flash

If you are getting errors on macOS about the device not being found, try running this first to unload the native FTDI driver:

sudo kextunload -b com.apple.driver.AppleUSBFTDI

Atom Highlighting Plugin

You can highlight .hdl scripts in Atom. Run the following to install the Atom Plugin:

cd language-hoodlum
apm link --local .

Hoodlum Tutorial

A Hoodlum script is composed of entity definitions in entity blocks, and logic definitions are in impl blocks. The topmost entity is the Main block.

entity Main {
    in clk: bit,
    out LED1: bit,
}

These top level entries reference pin definitions in your .pcf file; see "examples/blinky/icestick.pcf" for one for the iCEstick evaluation board.

Each of these entity members declares:

• A direction: in indicates a value will be read by the entity, and out indicates a value will be written by the entity.
• A name. This can be referenced by name in the impl block.
• A type. Here, we declare both values to be one bit wide, i.e. a logic value of either 0 or 1 (or x, in more complicated logic).

Inside of a corresponding impl block, we can reference these values:

impl Main {
    def mut toggle: bit;

    def toggle_next: bit = !toggle;

    on clk.negedge {
        toggle <= toggle_next;
    }

    LED1 = toggle;
}

Let's break this down. First, we define a variable "toggle" which is one bit wide. We declare this as def mut, meaning the variable is mutable inside of a on block.

Next, we define a variable "toggle_next" which is not mutable. This means we have a stateless definition that requires no state (latches or flip-flops). We can declare its value inline with the definition or as a standalone declaration. Its value is always equal to the inverse of the "toggle" variable.

The on block has a sensitivity to either the positive or negative falling edge of a signal value. Inside of an on block we can make assignments to mutable variables using the nonblocking <= or blocking := operators. Here, every time we see a negative clock edge, we reset the "toggle" latch to be the value of "toggle_next", i.e. the inverse of itself.

(Nonblocking definitions are deferred until the end of the on block; this simplifies stateful logic to all be set on the same clock impulse.)

Last, we declare a value for our output variable. LED1 is set to always be equal to the value of the mutable "toggle" value.

At 12Mhz, you won't be able to see the LED toggling at this speed! See "examples/blinky/blinky.hdl" for how to use a counter to make it visible.

Types

Each definition has a type, declared by the format def [mut] name: <type>.

• bit declares a value that can hold 0, 1, or x.
• bit[n] declares a port that is n bits wide. You can reference individual bits using a slice operator (e.g. myvariable[1]) and set it at once with a numeric literal (e.g. myvariable = 0b101101, etc.)
• uint{..n} and int{..n} declares integers (unsigned and signed) whose max value is n (to the nearest power of two). This is shorthand for calculating the maximum bit length for a given integer.

Inside an entity, you can also define sub-entities:

entity Toggle {
    in value: bit,
    out opposite: bit,
}

impl Toggle { ... }

entity Main { ... }

impl Main {
    def clk_prime: bit;
    def toggle = Toggle {
        value: clk,
        opposite: clk_prime,
    }
}

Main declares a sub-entity Toggle with an input value given as "clk" and a output value as "clk_prime". Note that you have to declare output variables alongside the sub-entity to use them.

Contributing

Open up any issues, discussion, ideas, or bugs in the issue tracker.

Language Design Goals

Goals:

1. Define a hardware description language that's elegant, borrowing syntax from Rust syntax and other modern (familiar) languages.
2. Emit compatible Verilog-2001 (and VHDL) code.
3. Create abstractions to simplify generation of state machines, sequential code, and reset states.
4. Hackable so you can add your own constructs.
5. Statically detect errors before they reach synthesis stage.
6. In the future, add simulation capabilities.

Non-goals:

1. Don't compile Rust into HDL. Rust's stdlib fits an entirely different computing model. The abstraction mismatch makes code that's hard to debug.
2. Don't support compiling all features of Verilog-2001 or VHDL, just a functional subset.

License

MIT or Apache-2.0.