Documentation bench

Read Verilog documentation by the question it answers

A language reference, a tutorial, a synthesis manual, and a simulator guide can all describe valid Verilog while solving entirely different problems.

Four layers of documentation

The language standard defines syntax and semantics. It is the authority for questions such as how an expression is sized, when a procedural event occurs, or what a system task means. It is not usually the fastest first explanation for a new designer. A tutorial supplies a mental model and small examples, but it may simplify corners deliberately. A tool manual explains a particular implementation: command-line switches, supported language modes, waveform formats, diagnostics, and extensions. A methodology guide explains how a team uses the language to build maintainable and verifiable hardware.

Confusion appears when one layer is asked to answer for another. A simulator accepting a construct does not prove that synthesis can implement it. A synthesis warning does not redefine the language. A tutorial pattern that works for a small example may be a poor reset or clock-domain policy for a large design. Name the layer before searching and discrepancies become easier to resolve.

Language and semantics

Use a language reference for lexical rules, modules and ports, nets and variables, expressions, procedural blocks, continuous assignments, tasks and functions, timing controls, compiler directives, and the programming-language interface. Pay special attention to the revision named by a tool. A parser in an older mode can reject syntax that is valid in a newer language family.

Design and synthesis

Use design guides for coding intent: complete combinational assignments, clocked state, reset strategy, parameterization, finite-state machines, memories, arithmetic, and hierarchy. Then consult the synthesis manual for inference rules and target-specific limits. Portable RTL is the overlap between language semantics, common synthesis support, and the design rules your project can enforce.

Simulation and verification

Simulator documentation owns compilation order, library mapping, elaboration, plus-arguments, timescale handling, tracing, assertion controls, and exit status. Verification material owns stimulus architecture, reference models, checkers, coverage, randomization, and failure triage. A waveform viewer documents display and navigation; it does not define the event scheduler that produced the trace.

A disciplined reading method

Begin with a minimal example that isolates one rule. Record the language version, tool version, command line, timescale, and exact diagnostic. Reduce the example until unrelated modules and macros disappear. Then compare the observed result with the standard and the tool manual. This method is slower than guessing for five minutes and much faster than carrying a false rule through a codebase.

Examples should be treated as experiments. Change one dimension at a time: signedness, width, assignment kind, delay, edge, or port declaration. Add a self-checking condition so the expected result is explicit. If the behavior differs between tools, distinguish a legitimate implementation choice from a defect or an accidental extension. A compact reproducible case is also the most useful input to a bug report.

The directory's topic map

The original documentation desk grouped FAQs, quick references, on-line handbooks, design notes, synthesis material, programming-language interface introductions, and collections maintained by experienced tool builders. That taxonomy still maps cleanly onto real work. A new reader benefits from a tutorial and a small compiler exercise; an experienced designer often needs a precise semantic rule; an integration engineer needs command and library details; a verification engineer needs scheduling and interface behavior.

A useful local documentation set therefore includes the applicable language specification, the manuals for the exact tools in the flow, coding and lint rules, clock and reset policies, testbench conventions, and a short record of known deviations. Keep examples beside those rules and run them in continuous integration. Documentation becomes substantially more valuable when it can detect that a compiler upgrade changed an assumption.

Current reference endpoints

The following project manuals are useful because they expose concrete compiler, simulation, synthesis, and waveform workflows. They are examples of tool documentation, not a universal compatibility promise. Check the language mode and supported-feature pages for the release you actually run.

• Icarus Verilog documentation — compiler usage, language support, extensions, and simulation workflow.
• Verilator User Guide — compilation, linting, tracing, and integration reference.
• Yosys documentation entry point — synthesis framework concepts and command-oriented flows.