CLK_I

Chapter 3.7 closed Module 3 with every Wishbone signal named and none of them explained. Module 4 pays that off, signal by signal, and it starts with the one every other signal is defined against.

What exactly does the Wishbone clock establish — and what does it not imply?

1. Where the Clock Comes From

CLK_I is an input to every Wishbone interface — master, slave and interconnect alike. Nobody on the bus generates it.

Chapter 3.1 introduced the module that does: SYSCON, defined by the specification as "a WISHBONE module that drives the system clock [CLK_O] and reset [RST_O] signals." SYSCON is not an interface — it has no CYC, no STB, no address. It is the thing that supplies the time base, and it sits outside the master/slave relationship entirely.

One consequence that is easy to miss: because CLK_I is an input everywhere, a Wishbone interface has no opinion about frequency. The same master and slave RTL is correct at 10 MHz and at 200 MHz, and nothing in the interface changes.

2. What the Specification Actually Says — and Where

The clock's contract is split across two places in the B3 document, and which place a sentence comes from decides how much weight it carries. Getting this wrong is the source of a persistent piece of Wishbone folklore, so it is worth separating carefully.

From the numbered rules, in the timing chapter:

RULE 5.00 — "The clock input [CLK_I] to each IP core MUST coordinate all activities for the internal logic within the WISHBONE interface."

RULE 5.05 — "The WISHBONE interface MUST use synchronous, RTL design methodologies that, given nearly infinitely fast gate delays, will operate over a nearly infinite range of clock frequencies on [CLK_I]."

From the CLK_I signal description in the interface chapter — descriptive prose, not a numbered rule:

"The clock input [CLK_I] coordinates all activities for the internal logic within the WISHBONE interconnect. All WISHBONE output signals are registered at the rising edge of [CLK_I]. All WISHBONE input signals are stable before the rising edge of [CLK_I]."

The difference is not pedantry. RULE 5.00 is a MUST. The signal description contains no MUST at all — it is written in the declarative present, describing how the interface is expected to look, and it appears in the chapter that introduces the signals rather than the chapter that states the timing requirements.

What is genuinely normative, then:

One clock coordinates the interface (RULE 5.00). No half-cycle timing, no separate strobe clock, no activity referenced to anything else.

The methodology is synchronous RTL (RULE 5.05), characterisable across a wide frequency range — which is what the supporting text is about:

PERMISSION 5.00 — "The user's place and route tool MAY be used to enforce RULE 5.00."

OBSERVATION 5.00 — "Most place and route tools can be easily configured to enforce RULE 5.00. Generally, it only requires a single timing specification for Tpd,clk-su."

Engineering interpretation. RULE 5.00 together with its permission and observation is a timing-closure obligation: the design must be characterisable by a single clock-to-setup number, which is what a fully synchronous interface gives you. That is a statement about design methodology, not a prohibition on any particular output being combinational.

3. The Other Clock Rules, Which Are Concrete

Three further rules and permissions govern CLK_I, and all of them are things an integrator can get wrong.

RULE 5.10 — "The clock input [CLK_I] MUST have a duty cycle that is no less than 40%, and no greater than 60%."

Why a bus specification cares about duty cycle at all. A synchronous interface that only ever samples on the rising edge should, in principle, not care about the low time. It cares because real logic does: a badly asymmetric clock shortens one phase, and any circuit that depends on the low phase — a latch, a clock-gating cell's enable window, a memory's internal timing — loses margin. The 40–60% band is the specification declining to let an integrator hand a core a clock its internals cannot use.

PERMISSION 5.10 — "The SYSCON module MAY use a variable clock generator. In these cases the clock frequency can be changed by the SYSCON module so long as the clock edges remain clean and monotonic, and if the clock does not violate the duty cycle requirements."

So frequency scaling is explicitly allowed, and the conditions are about edge quality rather than about the bus. Nothing in a Wishbone interface has to be told the frequency changed.

PERMISSION 5.15 — "The SYSCON module MAY use a gated clock generator. In these cases the clock shall be stopped in the low logic state."

SUGGESTION 5.00 — "When using a gated clock generator, turn the clock off when the WISHBONE interconnection is not busy."

Stopping in the low state is the part with teeth. Stopping high leaves every flop having just sampled, with the next rising edge arbitrarily far away — and any circuit expecting a low phase stalls mid-operation. Stopping low leaves the interface in a clean quiescent state that a later rising edge resumes from.

RULE 5.05 — "The WISHBONE interface MUST use synchronous, RTL design methodologies that, given nearly infinitely fast gate delays, will operate over a nearly infinite range of clock frequencies on [CLK_I]."

OBSERVATION 5.05 — "Realistically, the WISHBONE interface will never be expected to operate over a nearly infinite frequency range."

Read RULE 5.05 as a prohibition, not an aspiration. It forbids anything whose correctness depends on a particular frequency: delay lines, ring oscillators, pulse-width tricks, "wait about 100 ns" counters calibrated to one clock. A design containing any of those works at one frequency and is broken at another — and OBSERVATION 5.05 is the specification acknowledging that the wording is deliberately extreme to make the prohibition unambiguous.

And OBSERVATION 5.10 notes the interface "assumes that a low-skew clock distribution scheme is used on the target device" — which is an assumption about the platform, not a requirement on the IP.

4. What the Clock Does Not Guarantee

This is the misconception that costs the most, so it gets its own section.

A synchronous bus does not mean a fixed-latency bus. Nothing in RULE 5.00 or anywhere else in the clock's contract says how many rising edges a transfer takes. The clock says when things are observed; it says nothing about how many observations a transfer needs.

Chapter 3.7 established the mechanism: in Wishbone Classic there is no stall signal, so a slave that needs time simply withholds its termination, and the master keeps holding its request across as many rising edges as that takes. The clock is what makes "as many rising edges as that takes" a well-defined statement rather than a vague one.

Nor does one clock input mean one clock domain in the system. CLK_I establishes a single reference for this interface. A peripheral whose internals run on a baud clock, a PHY clock or an off-chip reference has more than one domain inside it, and the Wishbone interface does not solve that crossing. The block must synchronise properly on its own side, and Chapter 3.4's GPIO slave carries a two-flop synchroniser for exactly that reason.

Two interfaces on different clocks are not connectable by wire. Joining a master on one clock to a slave on another needs a clock-domain-crossing bridge — a real design with handshakes or an asynchronous FIFO, and its own verification. Wishbone does not make that go away, and a design that simply connects them has an unsynchronised multi-bit crossing, which fails intermittently under exactly the conditions nobody tests.

5. RTL — The Clocked Interface Skeleton

Every Module 4 module is built on this shape, so it is worth establishing once.

// ─────────────────────────────────────────────────────────────────────────
// wb_clk_skeleton — the shape every Wishbone interface in Module 4 shares.
//
// PURPOSE. Establish the synchronous discipline once: interface state
// changes only at the rising edge of clk_i, inputs are read as sampled
// values, and nothing anywhere depends on a signal's value between edges.
//
// This module does not implement a transfer. It exists so that the
// structure is visible without any protocol content competing for
// attention — Chapter 4.8 onward fills it in.
//
// Reset is SYNCHRONOUS and ACTIVE HIGH throughout Module 4; Chapter 4.2
// is where that convention is derived from RULES 2.30 and 3.00.
// ─────────────────────────────────────────────────────────────────────────
module wb_clk_skeleton #(
  parameter int unsigned DW = 32
) (
  // ── From SYSCON. Both are inputs at EVERY interface; nobody on the bus
  //    generates either of them (Chapter 3.1).
  input  logic          clk_i,
  input  logic          rst_i,

  // ── A stand-in for any qualified Wishbone input (Chapter 4.8 makes this
  //    concrete as cyc_i & stb_i).
  input  logic          qualified_i,
  input  logic [DW-1:0] dat_i,

  output logic [DW-1:0] captured_o,
  output logic          seen_o
);
  // ── CORRECT. One always_ff, one edge, one clock. `dat_i` is read as the
  //    value it held at the rising edge. The CLK_I signal description's
  //    statement that inputs are stable before the rising edge is what
  //    entitles this module to treat that value as meaningful.
  always_ff @(posedge clk_i) begin
    if (rst_i) begin
      captured_o <= '0;
      seen_o     <= 1'b0;
    end else begin
      seen_o <= qualified_i;
      if (qualified_i) captured_o <= dat_i;
    end
  end

  // ── Three things this module deliberately does NOT do, each of which
  //    would break RULE 5.00 or RULE 5.05:
  //
  //   always_ff @(negedge clk_i)      — a second sampling instant. The
  //                                     interface is defined against the
  //                                     RISING edge only.
  //
  //   always_ff @(posedge some_other) — Wishbone-visible state on a
  //                                     different clock. That is a domain
  //                                     crossing and needs a bridge.
  //
  //   #10 or a delay-calibrated count — correctness that depends on a
  //                                     particular frequency, which
  //                                     RULE 5.05 forbids.
endmodule

Reading this module

Purpose. Make the synchronous discipline concrete before any protocol content competes for attention.

Ports. clk_i and rst_i from SYSCON; a stand-in qualified input; a data input; two registered outputs.

Ownership. This interface drives only captured_o and seen_o. Everything else it reads.

Combinational logic. None, deliberately. Every output comes from a flop — the shape the CLK_I signal description describes, and the one that gives the single Tpd,clk-su characterisation OBSERVATION 5.00 mentions.

Sequential logic. Two registers, updated on the rising edge and only there.

Timing. At each rising edge the module samples qualified_i and, if it is high, dat_i. Both outputs change at that edge and are stable across the following cycle.

Qualification. dat_i is captured only when qualified_i is high. Capturing unconditionally would store whatever happened to be on the bus — the mistake Chapter 4.5 is about.

Reset. Synchronous and active high, establishing a defined state at the first rising edge after assertion. Chapter 4.2 derives that from the rules.

Simplifications. No transfer, no termination, no address. It is a shape, not a device.

Failure modes. Sampling on negedge introduces a second observation instant the interface does not define. Clocking Wishbone-visible state on another clock creates an unsynchronised crossing. Any delay-calibrated timing violates RULE 5.05.

Verification. Section 6.

6. Waveform — What "Sampled at the Rising Edge" Means

Cycle 4 is the teaching point. dat_i carries 0x3C, and the interface never sees it — not because the value was invalid, but because no rising edge occurred while qualified_i was high to observe it. A Wishbone interface has exactly one opportunity per cycle to learn anything, and that is what makes the rest of Module 4's timing statements precise rather than approximate.

7. Failure Modes and Discriminating Evidence

Symptom: a transfer behaves correctly in simulation and intermittently wrongly in hardware.

Candidate causes. A Wishbone-visible register clocked on negedge. An interface signal crossing from another clock domain without synchronisation. A gated clock stopped in the high state.

Discriminating evidence. Search the design for negedge clk_i on anything the bus can see — one grep. Then check whether any interface signal's source register is clocked by something other than clk_i; a clock-domain report from synthesis is the fastest way. If both are clean, capture the clock itself during an idle period and check whether it stops high.

Likely RTL location. The sensitivity list of the offending always_ff, or the boundary where the signal originates.

Property. Hard to assert directly, which is why this is a review-and-report finding rather than a simulation one. The structural checks above are the practical answer.

Symptom: the system works at one clock frequency and fails at another.

Candidate causes. Correctness that depends on frequency — a counter calibrated to a particular period, a delay line, an assumption that some external event completes within N cycles.

Discriminating evidence. Sweep the frequency and look for a threshold. A clean threshold points at timing closure; a failure that appears at low frequency as well as high points at a frequency-dependent assumption, because timing closure only gets easier as you slow down.

Likely RTL location. Any counter whose terminal value was chosen from a time rather than from a cycle count.

Property. RULE 5.05 is the rule being violated, and the honest check is a design review rather than an assertion.

Symptom: a peripheral's registers read correctly but its pin-derived status is occasionally wrong.

Candidate causes. An asynchronous input sampled into the Wishbone clock domain without a synchroniser.

Discriminating evidence. Identify which of the slave's inputs are asynchronous to clk_i and check each for a two-flop chain. The symptom's rarity is itself evidence — metastability-driven failures are rare and load-dependent.

Likely RTL location. The slave's input path, not its bus interface.

8. Common Mistakes

"Synchronous means every transfer takes one cycle."

Wrong mental model: a clocked bus has fixed latency.

Concrete bug: a master that samples read data a fixed number of edges after asserting its request, which works against the slave it was tested with and returns the wrong value against any slower one.

Observable evidence: reads returning the previous transfer's data when a new peripheral is added — the pattern Chapter 3.7 identified as diagnostic.

Correct model: the clock defines when signals are observed, not how many observations a transfer needs. In Classic, a slave that needs time withholds its termination and the master keeps holding.

"CLK_I means the whole design is in one clock domain."

Wrong mental model: one clock input implies one domain.

Concrete bug: a UART slave sampling its receive line directly into a Wishbone-visible register with no synchroniser, or two interfaces on different clocks wired together.

Observable evidence: rare, load-dependent corruption that disappears under a logic analyser and is unreproducible in simulation.

Correct model: CLK_I is the reference for this interface. Anything arriving from another domain must be synchronised by the block itself, and joining two differently-clocked interfaces needs a bridge with its own design and verification.

"The duty-cycle rule is a formality."

Wrong mental model: only the rising edge matters, so the low phase is irrelevant.

Concrete bug: a core given a 25% duty-cycle clock from a divider, whose internal latch-based or clock-gated logic loses margin on the short phase.

Observable evidence: a core that fails on one board's clocking scheme and works on another at the same frequency.

Correct model: RULE 5.10 requires 40–60%. The bus samples on one edge; the logic inside the core does not necessarily, and the rule protects it.

"Gating the clock is free."

Wrong mental model: stopping a clock is neutral because nothing is happening.

Concrete bug: a gated clock stopped in the high state, leaving flops just past a sampling edge and any low-phase-dependent circuit suspended mid-operation.

Observable evidence: a system that resumes incorrectly after an idle period, with the fault correlated to idleness rather than to traffic.

Correct model: PERMISSION 5.15 allows gating and requires the clock to be stopped in the low state. SUGGESTION 5.00 is the specification actively encouraging gating when the interconnect is idle — it is a supported power technique with one condition.

9. Interview Reasoning

10. Understanding Check

11. What's Next

The clock establishes the observation model every other signal is defined against: one reference, one sampling edge, a duty-cycle band, permission to scale or gate it, and a prohibition on anything whose correctness depends on the frequency. It guarantees nothing about transfer length and does not solve a domain crossing.

One signal shares the clock's status as an input from SYSCON rather than part of any transfer, and it is the one an engineer coming from most other RTL will get wrong on both polarity and synchronicity.

What state must a Wishbone interface establish when reset is asserted, how long must it be held, and why is the convention the opposite of what most RTL uses?

Chapter 4.2 — RST_I answers it. The full path is on the Wishbone curriculum index.