skalp Tutorial

Learn skalp by Building Real Hardware

This tutorial takes you from zero skalp knowledge to a fully-featured UART peripheral with FIFOs, clock domain crossings, safety mechanisms, and a complete test suite. Each chapter introduces a language feature with a small standalone example, then applies it to the running UART project.

By the end, you’ll have built:

A UART transmitter with baud rate generation and FSM control
A UART receiver with mid-bit sampling and edge detection
Parameterized FIFOs with generic width and depth
Struct-based configuration and status ports
Enum-driven state machines with exhaustive pattern matching
Clock domain crossing safety with dual-clock async FIFOs
Safety annotations including TMR, trace, and breakpoint infrastructure
A Rust testbench with full coverage of the UART peripheral

Prerequisites

This tutorial assumes you already know how to design digital hardware. You should be comfortable with:

RTL concepts: registers, combinational logic, clock edges, reset
State machines, counters, shift registers
Basic UART protocol (start bit, data bits, stop bit)
Either SystemVerilog or VHDL (comparisons throughout use SystemVerilog)

You do not need to know Rust, though familiarity helps for Chapter 10 (testing). The tutorial explains Rust-specific concepts where they appear.

Installation

Install skalp from source:

git clone https://github.com/girivs82/skalp.git
cd skalp
cargo build --release

Add the binary to your PATH:

export PATH="$PATH:$(pwd)/target/release"

Verify:

skalp --version

Create a new project for the tutorial:

skalp new uart-tutorial
cd uart-tutorial

This creates a project with skalp.toml and a src/ directory. Each chapter adds files to this project.

Chapters

Getting Started — Entities, signals, on(clk.rise), and your first counter. The entity/impl split, port declarations, basic types.
State Machines — UART Transmitter — Build the UART TX with FSM states, baud rate timing, and shift register serialization.
UART Receiver — Mid-bit sampling, edge detection, bit reconstruction. The RX side of the UART.
Arrays and Generics — FIFO Buffering — Array types, generic parameters, clog2(). Build a parameterized FIFO and add buffering to the UART.
Const Generics and Parameterization — Generic defaults, compile-time computation, test vs. production parameters. Make the UART fully configurable.
Structs and Hierarchical Composition — Struct definitions, struct ports, hierarchical instantiation. Clean up the UART with structured configuration.
Enums and Pattern Matching — Enum types, match expressions, exhaustiveness checking. Refactor FSM states and add a command parser.
Clock Domain Crossing — Clock lifetimes, CDC compile-time safety, dual-clock entities, async FIFOs. Make the UART dual-clock.
Safety and Annotations — #[safety_mechanism], TMR voting, #[trace], #[breakpoint]. Add safety infrastructure to the UART.
Testing and Verification — Rust testbench API, test organization, waveform generation. Build a complete test suite for the UART.

What This Tutorial Doesn’t Cover

This tutorial focuses on the skalp language and workflow. For deeper topics, see:

Compiler internals and architecture — skalp project page
Null Convention Logic (async circuits) — NCL blog post
Production design patterns — Design Patterns in Real skalp Code

Ready? Start with Chapter 1: Getting Started.

Chapter 1: Getting Started

Your first skalp entity — an 8-bit counter that introduces the entity/impl split, port declarations, signal types, sequential logic with on(clk.rise), and combinational assignment.

Chapter 2: State Machines — UART Transmitter

Build a complete UART transmitter with FSM states, baud rate timing, and shift register serialization. Covers state encoding, counter-based timing, bit-level data shifting, and forward references for combinational signals.

Chapter 3: UART Receiver

Mid-bit sampling, edge detection, and bit reconstruction — build the RX side of the UART.

Chapter 4: Arrays and Generics — FIFO Buffering

Array types, generic parameters, and clog2() — build a parameterized FIFO and add buffering to the UART.

Chapter 5: Const Generics and Parameterization

Make your designs fully configurable with generic defaults, explicit instantiation, compile-time width computation, const expressions, and test vs. production parameterization – all applied to the running UART project.

Chapter 6: Structs and Hierarchical Composition

Group related signals into structs for cleaner interfaces, then compose entities hierarchically with let-binding to build the complete UART top-level module.

Chapter 7: Enums and Pattern Matching

Enum types with explicit bit encoding, match expressions that return values, exhaustiveness checking that catches missing cases at compile time — refactor FSM states and build a UART command parser.

Chapter 8: Clock Domain Crossing

Clock domain lifetimes, CDC compile-time safety, dual-clock entities, 2-flop synchronizers, Gray code pointers, and async FIFOs — make the UART dual-clock with compile-time guarantees against metastability bugs.

Chapter 9: Safety and Annotations

Add safety mechanisms and debug infrastructure to your designs with TMR voting, detection signals, retention hints, trace grouping, and simulation breakpoints – all zero-cost annotations that travel with your source code.

Chapter 10: Testing and Verification

Rust testbench API in depth – Testbench::new(), tb.set(), tb.clock(), tb.expect(), tb.get(). Test organization, helper functions, multiple test cases, waveform generation with VCD, and a complete UART test suite.

Learn skalp by Building Real Hardware#

Prerequisites#

Installation#

Chapters#

What This Tutorial Doesn’t Cover#

Learn skalp by Building Real Hardware

Prerequisites

Installation

Chapters

What This Tutorial Doesn’t Cover