# hello-world-verilog

A minimal, synthesizable "hello world" for an FPGA or ASIC flow: one counter, one LED that blinks at
a parameterised frequency, and a self-checking testbench. It is small enough to read in a minute and
real enough to drop into a vendor project unchanged.

## Files

| Path | What it is |
|---|---|
| `rtl/hello.v` | the design: `hello` blinks `led` at `BLINK_HZ` from a `CLK_HZ` clock |
| `tb/tb_hello.v` | self-checking testbench: counts edges and fails if the toggle interval is wrong |
| `sim/run.sh` | one command to simulate with Icarus Verilog |

## How to use it

Simulate (needs `iverilog` and `vvp`; on Debian/Ubuntu `apt install iverilog`):

```sh
cd sim && ./run.sh
```

Expected output ends with:

```
[TB] 8 toggles observed, interval = 4 cycles -> PASS
```

Synthesise: add `rtl/hello.v` to your project and set the two parameters for your board, for example

```verilog
hello #(.CLK_HZ(50_000_000), .BLINK_HZ(1)) u_hello (
  .clk(clk),
  .rst_n(rst_n),
  .led(led)
);
```

`CLK_HZ / BLINK_HZ` must be at least 4; the design then toggles the LED once per half period.

## Ports

| Port | Dir | Width | Meaning |
|---|---|---|---|
| `clk` | in | 1 | clock, any frequency up to a few hundred MHz |
| `rst_n` | in | 1 | asynchronous reset, active low |
| `led` | out | 1 | toggles at `BLINK_HZ` |

## Licence

MIT — see `LICENSE`.