State machines
You will learn
How a synthesizer finds a state machine in your design, or refuses to.
Many designs are state machines: a register that holds the current state and logic that picks the next one. yosys looks for them and, when it finds one, can re-encode it. When it refuses, it says why. The widget draws the graph yosys extracted from real designs, a UART receiver and a SPI flash master, and shows a case it refused.
Try it
Open the uart_rx sample and count its states and transitions. The JTAG port runs a state machine too: in the spec frame, find the test that says how many states the TAP controller has.

Drop a yosys fsm_export KISS2 file or paste the fsm_info log: the state diagram yosys extracted, its states, transitions and inputs, and the registers it refused.
specs/fpga/dft.t27
// SPDX-License-Identifier: Apache-2.0
// t27/specs/fpga/dft.t27
// T27 Design-for-Test Specification
// Scan chains, BIST controllers, JTAG TAP, test coverage estimation
// Uses flat arrays + count fields (parser-compatible)
// phi^2 + 1/phi^2 = 3 | TRINITY
module DFT {
// === Scan chain ===
pub struct ScanChain {
name : &str,
num_regs : u32,
chain_length_bits : u32,
}
fn scan_chain(name: &str, regs: u32) -> ScanChain {
return ScanChain{
.name = name,
.num_regs = regs,
.chain_length_bits = regs * 32,
};
}
fn scan_chain_cycles(chain: ScanChain) -> u32 {
return chain.chain_length_bits + 10;
}
fn scan_chain_bytes(chain: ScanChain) -> u32 {
return chain.chain_length_bits / 8;
}
// === BIST kind ===
pub const BistKind = enum(i8) {
memory_bist = 0,
logic_bist = 1,
io_bist = 2,
}
// === BIST controller ===
pub struct BistCtrl {
name : &str,
kind : i8,
patterns : u32,
pass_threshold : u32,
}
fn memory_bist(name: &str, patterns: u32) -> BistCtrl {
return BistCtrl{
.name = name,
.kind = 0,
.patterns = patterns,
.pass_threshold = patterns,
};
}
fn logic_bist(name: &str, patterns: u32) -> BistCtrl {
return BistCtrl{
.name = name,
.kind = 1,
.patterns = patterns,
.pass_threshold = patterns,
};
}
fn bist_cycles(ctrl: BistCtrl) -> u32 {
return ctrl.patterns * 2;
}
fn bist_coverage(ctrl: BistCtrl, total_faults: u32) -> u32 {
if total_faults == 0 {
return 100;
}
return ctrl.patterns * 100 / total_faults;
}
// === JTAG TAP ===
pub struct JtagTap {
name : &str,
ir_width : u32,
num_dr_regs : u32,
bypass_code : u32,
idcode : u32,
}
fn jtag_tap(name: &str, ir_width: u32, idcode: u32) -> JtagTap {
return JtagTap{
.name = name,
.ir_width = ir_width,
.num_dr_regs = 3,
.bypass_code = 255,
.idcode = idcode,
};
}
fn tap_total_bits(tap: JtagTap) -> u32 {
return tap.ir_width + 32 * tap.num_dr_regs;
}
fn tap_state_count() -> u32 {
return 16;
}
// === Test coverage ===
pub struct TestCoverage {
scan_coverage : u32,
bist_coverage : u32,
atpg_coverage : u32,
total_coverage : u32,
}
fn test_coverage(scan: u32, bist: u32, atpg: u32) -> TestCoverage {
return TestCoverage{
.scan_coverage = scan,
.bist_coverage = bist,
.atpg_coverage = atpg,
.total_coverage = (scan + bist + atpg) / 3,
};
}
fn is_acceptable(cov: TestCoverage) -> bool {
return cov.total_coverage >= 90;
}
// === Validation ===
fn validate_chain(chain: ScanChain) -> u32 {
var errors : u32 = 0;
if chain.name == "" {
errors = errors + 1;
}
if chain.num_regs == 0 {
errors = errors + 1;
}
return errors;
}
fn validate_bist(ctrl: BistCtrl) -> u32 {
var errors : u32 = 0;
if ctrl.name == "" {
errors = errors + 1;
}
if ctrl.patterns == 0 {
errors = errors + 1;
}
return errors;
}
fn validate_tap(tap: JtagTap) -> u32 {
var errors : u32 = 0;
if tap.name == "" {
errors = errors + 1;
}
if tap.ir_width == 0 {
errors = errors + 1;
}
return errors;
}
// === Tests ===
test scan_chain_creation
given c = scan_chain("core_chain", 100)
then c.num_regs == 100
and c.chain_length_bits == 3200
and scan_chain_cycles(c) == 3210
and scan_chain_bytes(c) == 400
test memory_bist_creation
given b = memory_bist("bram_bist", 8)
then b.kind == 0
and b.patterns == 8
and bist_cycles(b) == 16
test logic_bist_creation
given b = logic_bist("logic_bist", 16)
then b.kind == 1
and b.patterns == 16
test bist_coverage_full
given b = memory_bist("bist", 100)
then bist_coverage(b, 100) == 100
test bist_coverage_partial
given b = memory_bist("bist", 50)
then bist_coverage(b, 200) == 25
test bist_coverage_zero_faults
given b = memory_bist("bist", 10)
then bist_coverage(b, 0) == 100
test jtag_tap_creation
given t = jtag_tap("main_tap", 8, 305419896)
then t.ir_width == 8
and t.num_dr_regs == 3
and t.bypass_code == 255
and tap_total_bits(t) == 104
test tap_state_count
then tap_state_count() == 16
test test_coverage_creation
given c = test_coverage(95, 90, 85)
then c.scan_coverage == 95
and c.bist_coverage == 90
and c.atpg_coverage == 85
and c.total_coverage == 90
test test_coverage_acceptable
given c = test_coverage(95, 95, 90)
then is_acceptable(c) == true
test test_coverage_not_acceptable
given c = test_coverage(80, 80, 80)
then is_acceptable(c) == false
test validate_chain_ok
given c = scan_chain("ok", 10)
then validate_chain(c) == 0
test validate_chain_empty
given c = ScanChain{.name = "", .num_regs = 0, .chain_length_bits = 0}
then validate_chain(c) > 0
test validate_bist_ok
given b = memory_bist("ok", 8)
then validate_bist(b) == 0
test validate_bist_empty
given b = BistCtrl{.name = "", .kind = 0, .patterns = 0, .pass_threshold = 0}
then validate_bist(b) > 0
test validate_tap_ok
given t = jtag_tap("ok", 4, 0)
then validate_tap(t) == 0
test validate_tap_empty
given t = JtagTap{.name = "", .ir_width = 0, .num_dr_regs = 0, .bypass_code = 0, .idcode = 0}
then validate_tap(t) > 0
// === Invariants ===
invariant scan_cycles_positive
given c = scan_chain("inv", 10)
assert scan_chain_cycles(c) > 0
invariant coverage_bounded
given c = test_coverage(100, 100, 100)
assert c.total_coverage <= 100
// === Benchmarks ===
bench dft_latency
measure: nanoseconds for scan_chain("bench", 1000)
target: < 50ns
}
// phi^2 + 1/phi^2 = 3 | TRINITY
All lessons
Module 1 · The chip
What an FPGA is, which chip we use, and how its pins meet the board.
Module 2 · Numbers in hardware
Bits, trits and number formats, and what arithmetic costs in logic.
Module 3 · Your t27 program
Write a spec, test it, and see why compiling is not the same as being right.
Module 4 · Inside t27c
How the compiler reads a spec and what it writes, including the native t27b.
Module 5 · From spec to hardware
The Verilog t27c writes, the cells it becomes, and what one LUT does.
Module 6 · Reading synthesis
What yosys reports about your design, and which warnings matter.
Module 7 · Place, route, timing
Where the cells land on the die, and whether the clock is met.
Module 8 · The bitstream
How a routed design becomes the bits the chip loads, with no Vivado.
Module 9 · On the board
Ask the chip who it is, load the bits, and check them.