Control Data Stage

Chapter 13.1 declared a data stage of wLength bytes. This is that stage, and its rules are not quite Chapter 12.2's.

The difference is one word: declared. An ordinary transfer's length exists only in software at each end. A control transfer's length was transmitted, in the setup stage, and both ends know it.

Which gives this stage two ways to end instead of one — and a rule about size that an ordinary transfer does not need.

1. Two Terminations, Not One

Chapter 12.2 §2's rule was singular: a short packet is the last one. Here there are two independent endings:

The declared count is exhausted — wLength bytes have moved.

A short packet arrives first — the sender had less than it was asked for.

Both are normal, and they are not interchangeable. A transfer that ends because the count ran out was fully satisfied; one that ends short was not, and the difference is information the layer above needs.

And an ordinary bulk transfer has only the second, because there is no declared count to exhaust. §6's C4 is the mutation that removes the first — and its measurement is small, which §8 explains.

2. Fewer Is Allowed; More Never Is

The stage's one hard rule:

The device may return fewer bytes than wLength. It may never return more.

Fewer is routine. A host asking for 255 bytes of a descriptor that is 18 bytes long gets 18 and a short packet — and Chapter 13.5 shows that this is how descriptors are read at all, because their length is not known until they arrive.

More is a buffer overrun in the host. wLength is not a request; it is the size of the buffer the host allocated. A device that sends more has written past the end of it, and the host's protection is whatever its controller does about the excess — which is a hardware behaviour rather than a guarantee.

So the device's transmit length is capped by three things at once:

tx_len = min( wMaxPacketSize , remaining , what the device has )

All three, every packet. §6's C1 drops the middle term — and §8 is about why a bench naturally never notices.

3. The Descriptor Probe: When the Host Asks for Less Than Exists

The case that makes the remaining cap necessary, and it is the first control transfer of every enumeration.

A host reading a device descriptor has a bootstrap problem: the descriptor's length is in its first byte, and the host does not have the descriptor yet. So it asks for a small fixed amount first — commonly 8 bytes — reads bLength and bMaxPacketSize0 from what comes back, and then asks again for the full length.

From the device's side, that first request asks for less than exists. The descriptor is 18 bytes; wLength is 8. The device must send exactly 8 and stop.

4. Packet Size Here Is Not the Endpoint's Choice

A detail that catches people porting between speeds.

A control endpoint's wMaxPacketSize is constrained to a small set of values — and at high speed it is fixed at 64. It is also the field the descriptor probe of §3 exists to read, which produces a circularity the protocol resolves by fiat:

The host must be able to read the first 8 bytes of a device descriptor without knowing wMaxPacketSize0. Eight bytes is small enough to fit in the smallest legal control packet, so the probe works whatever the device turns out to declare — and bMaxPacketSize0 is at byte 7 of the descriptor, inside those eight.

The probe reads exactly enough to learn how to do everything else.

Which means wMaxPacketSize is a parameter of this stage rather than something it negotiates — and a device that hard-codes 64 works until it is a low-speed device, where the maximum is 8.

5. The Control Data Stage, as RTL

// ─────────────────────────────────────────────────────────────────────────
// usb_ctrl_data_stage
//
// Classification: SIMPLIFIED SYNTHESIZABLE TEACHING RTL. It models section
// 1's two terminations and section 2's cap.
//
// WHAT IT MODELS. Given a declared wLength and one completed packet, has the
// stage ended, and how -- plus, for an IN stage, how large the next packet
// is allowed to be.
//
// WHAT IT DOES NOT MODEL. The payload or its storage (Chapter 9.5); the
// transactions that carry each packet (Module 12); the SETUP that declared
// wLength (Chapter 13.1, consumed here as inputs); the status stage that
// follows (Chapter 13.3); and WHAT the bytes mean, which is Chapter 13.4.
//
// ── ON THE THREE-WAY CAP ────────────────────────────────────────────────
// Section 2: tx_len is min(maxp, remaining, available), and all three terms
// are load-bearing. `maxp` stops an oversized packet, `available` stops
// sending data that does not exist, and `remaining` stops overrunning the
// HOST's buffer -- which is the term a bench forgets, because forgetting it
// is invisible unless the device holds MORE than the host asked for. Section
// 8 measures exactly that.
// ─────────────────────────────────────────────────────────────────────────
module usb_ctrl_data_stage #(
  // Section 4: a parameter, not a negotiation. 8 at low speed, 8/16/32/64
  // at full speed, fixed at 64 at high speed.
  parameter int unsigned EP0_MAXP = 64
)(
  input  logic        clk,
  input  logic        rst_n,

  // From Chapter 13.1's decode, at the moment the SETUP completed.
  input  logic        setup_new,
  input  logic [15:0] wLength,
  input  logic        dir_is_in,

  input  logic        pkt_done,
  input  logic [15:0] pkt_len,

  // How many bytes the device actually holds for an IN stage.
  input  logic [15:0] avail,

  output logic [15:0] remaining,
  output logic        stage_active,
  output logic        stage_complete,
  output logic        ended_short,      // section 1: the sender had less
  output logic        ended_exhausted,  // section 1: the declared count ran out
  output logic        overrun,          // more than wLength -- illegal
  output logic [15:0] tx_len            // section 2's three-way cap
);

  logic [15:0] rem_q;
  logic        active_q;

  assign remaining    = rem_q;
  assign stage_active = active_q;

  logic is_short;
  assign is_short = pkt_done && (pkt_len < EP0_MAXP[15:0]);

  // A packet longer than what remains has written past the host's buffer.
  // It cannot be prevented here -- the bytes have already arrived -- but it
  // can be REPORTED, which is the only way a layer above learns of it.
  assign overrun = pkt_done && active_q && (pkt_len > rem_q);

  // ── SECTION 1'S TWO ENDINGS, kept separate ──────────────────────────────
  // They are not alternative spellings of "complete": one means the host got
  // everything it asked for and the other means it did not, and the layer
  // above needs to tell them apart.
  assign ended_short     = active_q && pkt_done && is_short;
  assign ended_exhausted = active_q && pkt_done && !is_short &&
                           (pkt_len >= rem_q);
  assign stage_complete  = ended_short || ended_exhausted;

  // ── SECTION 2'S CAP ─────────────────────────────────────────────────────
  // min(EP0_MAXP, rem_q, avail), written as nested selects rather than a
  // function so that all three terms are visible in one expression.
  assign tx_len = (rem_q  < EP0_MAXP[15:0])
                    ? ((avail < rem_q)            ? avail : rem_q)
                    : ((avail < EP0_MAXP[15:0])   ? avail : EP0_MAXP[15:0]);

  always_ff @(posedge clk or negedge rst_n) begin
    if (!rst_n) begin
      rem_q <= '0; active_q <= 1'b0;
    end else if (setup_new) begin
      rem_q    <= wLength;
      // Chapter 13.1 section 3: wLength of zero means there is NO data
      // stage. Arming anyway is section 6's C5, and it leaves the device
      // waiting for a transaction the host will never send.
      active_q <= (wLength != 16'd0);
    end else if (active_q && pkt_done) begin
      if (stage_complete) active_q <= 1'b0;
      rem_q <= (pkt_len >= rem_q) ? 16'd0 : (rem_q - pkt_len);
    end
  end

endmodule

What it models. The termination and sizing rules of one control data stage.

Engineering reason. Because a declared length creates a second way to end and a cap that an ordinary transfer does not have.

Inputs. The declared length and direction at setup time, a completed packet, and what the device holds.

State retained. A 16-bit remainder and an active flag — 17 flip-flops.

Outputs. The remainder, the stage's activity, both endings separately, an overrun report, and the transmit cap.

Hardware implied. A 16-bit subtractor and three comparators.

Reset behaviour. Cleared and inactive; a control transfer does not survive a reset.

Assumptions. That pkt_len counts payload bytes only; that avail is what the device can supply now; and that EP0_MAXP matches the value in the device descriptor's bMaxPacketSize0 — §4's circularity resolved, and a mismatch here is undetectable from inside this block.

Omissions. The payload, the transactions, the SETUP, the status stage and the request semantics — in the header.

What DV should verify. That a short packet always ends the stage; that an exhausted count also ends it; that the two endings are distinguished; that tx_len never exceeds any of its three caps — especially when the device holds more than was asked for; that wLength = 0 arms nothing; and that a packet longer than the remainder is reported.

6. Mutation Test

Five mutations over 1,432 checks across 413 data stages — directed cases for every relationship between wLength, wMaxPacketSize and what the device holds, plus 400 randomised stages and six deliberately illegal oversized packets.

The unmutated block: 402 stages ended short, 11 ended exhausted, 6 overruns detected, and 0 errors of every kind.

C1 — drop remaining from the transmit cap

Measured: 114 packets offering more bytes than the host had allowed — and 120 resulting overruns, against the golden design's 6 deliberate ones.

§3's hazard. The device sends everything it has, up to a packet, regardless of what the host asked for — so an 8-byte probe of an 18-byte descriptor returns 18.

And this mutation initially escaped the bench entirely. §8.

C2 — never classify a packet as short

Measured: 24 223 misclassifications, 160 stages that never ended, and short endings falling from 402 to zero.

The catastrophic contrast case, exactly as in Chapter 12.2 §6. Included because the next mutation produces the same category of failure at 0.05% of the volume.

C3 — do not detect an oversized packet

Measured: all 6 deliberate overruns undetected, and nothing else changed.

A packet longer than the remainder has already written past the host's buffer by the time this block sees it. The block cannot prevent it; it can only report it — and without the report, the layer that could act on it never learns.

It needs illegal stimulus to see at all, which is Chapter 12.2 §8's shape in a new place.

C4 — let only a short packet end the stage

Measured: 11 wrong — exactly the stages that ended by exhaustion.

§1's first ending removed. Eleven out of 413 is a 2.7% failure rate in this bench and close to 100% in practice, for the reason Chapter 12.2 §6 measured on the same shape: exhaustion happens when wLength is exactly what the device has, and real software asks for exactly what it wants.

Every SET_* request with a payload, every fixed-size vendor command, and every GET_STATUS — all exhaust rather than short-terminate.

C5 — arm the stage even when wLength is zero

Measured: 3 stages never ended.

Chapter 13.1 §3's rule. SET_ADDRESS and SET_CONFIGURATION have wLength = 0 and no data stage — a device that arms one waits for a transaction the host will never send, and only Chapter 12.5's timeout releases it.

Three occurrences, and they are the two most important requests in enumeration.

7. The Assertions

// ─────────────────────────────────────────────────────────────────────────
// Classification: TEACHING ASSERTIONS about the control data stage.
// T-properties are the two TERMINATIONS; L the length cap; A the arming.
// ─────────────────────────────────────────────────────────────────────────

// T1 -- A SHORT PACKET ALWAYS ENDS THE STAGE. Section 1's second ending,
// and identical to Chapter 12.2's rule.
property p_short_ends;
  @(posedge clk) disable iff (!rst_n)
    (stage_active && pkt_done && (pkt_len < EP0_MAXP)) |-> ended_short;
endproperty
assert property (p_short_ends);

// T2 -- AND SO DOES EXHAUSTING THE DECLARED COUNT. Section 1's FIRST
// ending, which an ordinary transfer does not have -- and section 6's C4.
property p_exhaustion_ends;
  @(posedge clk) disable iff (!rst_n)
    (stage_active && pkt_done && (pkt_len >= EP0_MAXP) && (pkt_len >= remaining))
      |-> ended_exhausted;
endproperty
assert property (p_exhaustion_ends);

// T3 -- AND THE TWO ARE DISTINGUISHED. Not merely "one of them fired": the
// layer above needs to know whether the host got everything it asked for,
// and a design that reports both, or the wrong one, tells it nothing.
property p_endings_exclusive;
  @(posedge clk) disable iff (!rst_n)
    stage_complete |-> (ended_short ^ ended_exhausted);
endproperty
assert property (p_endings_exclusive);

// L1 -- THE CAP HOLDS ON ALL THREE TERMS. Section 2, and section 6's C1.
// Written as three separate conjuncts rather than as a min() so that a
// failure names WHICH cap was exceeded.
property p_tx_len_capped;
  @(posedge clk) disable iff (!rst_n)
    stage_active |-> ( (tx_len <= EP0_MAXP)
                    && (tx_len <= remaining)
                    && (tx_len <= avail) );
endproperty
assert property (p_tx_len_capped);

// L2 -- AND IT IS THE LARGEST VALUE SATISFYING THEM. Without this, tx_len
// tied to zero satisfies L1 -- and a device that always sends nothing is a
// device that never completes a transfer.
property p_tx_len_maximal;
  @(posedge clk) disable iff (!rst_n)
    stage_active |-> (tx_len == ((EP0_MAXP < remaining)
                                  ? ((avail < EP0_MAXP) ? avail : EP0_MAXP)
                                  : ((avail < remaining) ? avail : remaining)));
endproperty
assert property (p_tx_len_maximal);

// L3 -- A PACKET LONGER THAN THE REMAINDER IS REPORTED. Section 6's C3. It
// cannot be prevented -- the bytes arrived -- so reporting is the whole of
// what this layer can do.
property p_overrun_reported;
  @(posedge clk) disable iff (!rst_n)
    (stage_active && pkt_done && (pkt_len > remaining)) |-> overrun;
endproperty
assert property (p_overrun_reported);

// A1 -- ZERO LENGTH ARMS NOTHING. Chapter 13.1 section 3, and section 6's C5.
property p_zero_length_no_stage;
  @(posedge clk) disable iff (!rst_n)
    (setup_new && (wLength == 16'd0)) |=> !stage_active;
endproperty
assert property (p_zero_length_no_stage);

// A2 -- AND A NON-ZERO ONE ARMS EXACTLY ONE STAGE.
property p_nonzero_arms;
  @(posedge clk) disable iff (!rst_n)
    (setup_new && (wLength != 16'd0)) |=> stage_active;
endproperty
assert property (p_nonzero_arms);

L1 and L2 are the pair that matters, and their asymmetry is deliberate. L1 says the cap is not exceeded; L2 says it is not undershot. A design satisfying only L1 sends nothing forever — which passes every safety property and completes no transfer, the shape Chapter 9.5 measured.

And L1's three conjuncts are kept separate rather than folded into a min() because a failing assertion is a diagnostic message: which cap was exceeded tells you whether the bug is in packetisation, in tracking the remainder, or in the device's own accounting, and those are three different investigations.

8. Verification

This chapter's commit point is the host received no more than it asked for, and knew whether it got everything.

Stimulus. No data stage at all; one short packet; exactly wMaxPacketSize; an exact multiple; the 255-byte descriptor read that returns 18; the 8-byte probe of an 18-byte descriptor; a request for 1 byte of 18; a request for 64 of 512; OUT stages of both shapes; 400 randomised stages with the device holding more or less than requested; and six deliberately oversized packets.

Observation. Both endings separately, the remainder, the transmit cap, and an independent check that the device never offered more than the host allowed — computed from the bench's own record of wLength, not from the design's remaining.

Reference model. The four rules of §§1–2 evaluated directly. Its independence is limited, which is why the offered-too-much check is stated against the bench's own bookkeeping instead.

And one further bench defect was fixed before these numbers were trustworthy: the bench read the combinational tx_len in the same time step it drove avail, before the continuous assignment had settled — producing 46 spurious failures on the correct design. A bench that reads a combinational output without letting it settle is measuring its own race, and the symptom — failures on a design you believe is right — invites weakening the check rather than fixing the timing.

Coverage — crosses:

• wLength greater than, equal to, and less than what the device holds — all three
• wLength modulo wMaxPacketSize: 0, 1, and mid-range
• wLength = 0 × each direction
• packet length: 0, 1, maxp − 1, maxp, greater than remaining
• multi-packet stages ending both ways

Negative cases with defined outcomes: tx_len never exceeds any of its three caps; a short packet never fails to end the stage; an exhausted count never fails to end it; both endings are never reported together; a zero wLength never arms a stage; and an oversized packet is always reported.

9. Debugging: the Descriptor That Reads Back Corrupted

A device enumerates on Linux and fails on Windows. On Windows the host reports a malformed device descriptor. An analyser shows the device transmitting a correct, complete 18-byte descriptor. The bytes on the wire are right.

If the bytes are right, what can be wrong? How many of them there are. The descriptor's content is correct and its length may not match what the host asked for.

What does the host ask for first? §3: a probe. Different hosts probe differently — some ask for 8 bytes, some for 18, some for 64. That is the one part of enumeration where hosts legitimately differ.

So what would break on one host and not another? A device that ignores wLength and always sends the whole descriptor. A host that probed with 64 gets 18 and a short packet — correct. A host that probed with 8 gets 18 into an 8-byte buffer.

Why does the analyser not flag it? Because the descriptor is well-formed and the packet is legal in isolation. The violation is a relationship between two packets — the wLength in the SETUP and the length of the data — and a decoder that shows each packet's contents does not compute it.

What is the decisive observation? Read the SETUP's wLength and compare it with the bytes returned. They are two fields in the same trace, several packets apart, and nothing shows the comparison unless you make it.

What if wLength and the returned length match? Then the device is right and the problem is the descriptor's own content — and §11's cross-check applies: bLength inside the descriptor must equal the number of bytes it actually is.

And why is Linux more forgiving? Not forgiveness — a different probe size. A host that happens to ask for at least as much as exists never exposes the missing cap. The device was always wrong and one host never asked the question.

The signature to keep: correct bytes, wrong count, differing by host is a wLength that was ignored — and it is found by comparing two packets that a per-packet decode never compares.

10. Common Misconceptions

11. Reason It Through

A device returns a 34-byte configuration descriptor. A host reads it in two steps: first with wLength = 9, then with wLength = 34. The device works. A second host reads it with wLength = 9 and then wLength = 255, and that host reports the descriptor as truncated.

What is different between the two hosts? Only the second wLength: 34 versus 255.

What does the device do in each case? With wLength = 34 it sends 34 bytes — exhausted, no short packet. With wLength = 255 it sends 34 bytes, which is short, and the transfer ends there.

So both hosts get 34 bytes. Why does one complain? Because 34 is not a multiple of wMaxPacketSize… unless it is. If the control endpoint's maximum is 64, then 34 is short and both cases terminate correctly. So that is not it.

What if the maximum is 8? Then 34 bytes is four full packets of 8 plus one of 2 — short, and correct. Still not it.

So where can a difference come from? From what the device does after it runs out. With wLength = 255 the device has sent 34 of 255 and the host has not had its count exhausted. If the device's last packet happened to be exactly wMaxPacketSize, there would be no short packet and the stage would not terminate — the host would wait for more.

When is 34 an exact multiple? Never of 8, 16, 32 or 64. But the device might not be sending 34. If it sends the total configuration length from wTotalLength while holding only the 9-byte header, or pads to a packet boundary, the arithmetic changes.

What is the actual most likely fault? That the device caches the length from the first request. It answered wLength = 9 with 9 bytes, remembered 9, and answers the second request with 9 as well — so the host with wLength = 34 sees 9 and stops (exhausted from its point of view is wrong, but 9 < 64 is short and it accepts a truncated read), while the host asking for 255 sees 9 bytes where 34 were promised in wTotalLength and correctly reports truncation.

How would you confirm it? Compare the bytes returned by the two reads. If the second returns the same 9 bytes as the first, the device is reusing state across transfers — Chapter 12.1's capture problem one level up.

And the transferable point: when two hosts disagree, the difference between them is the measurement. Neither host is wrong; one of them simply asked a question the device had never been asked. The most useful thing about a second implementation is the questions it asks differently.

12. Understanding Check

13. Summary

A control data stage has a declared length, which an ordinary transfer does not — so it has two ways to end: the count is exhausted, or a short packet arrives first. They mean different things and must be distinguished, because one says the host got everything it asked for and the other says it did not.

The device may return fewer bytes than wLength and never more, because wLength is the size of the host's buffer. Which makes the transmit length a three-way cap — min(wMaxPacketSize, remaining, available) — and all three terms load-bearing.

The middle term earns its place on the first transfer of every enumeration: §3's probe, where the host asks for 8 bytes of an 18-byte descriptor because the descriptor's length is inside the descriptor. Drop that term and the device writes ten bytes past the host's buffer — measured at 114 over-long offers producing 120 overruns.

§6's other results: never classifying short hangs everything immediately and never ships; letting only short end the stage fails 11 times in 413 here and constantly in production, because every fixed-size request exhausts rather than short-terminates; no overrun report needs illegal stimulus to see; and arming on a zero wLength hangs the two most important requests in enumeration.

And §8 is the chapter's finding, which is about a bench's shape rather than its coverage:

One line of the stimulus generator — drawing what the device holds as bounded by what the host asked for — made the single most common control transfer in USB impossible to produce.

It was written that way because it is a faithful model of a bulk transfer, where the device's supply is the only limit. The control data stage has two limits, and the generator encoded the one its author was thinking about.

A constraint between stimulus variables hides defects as effectively as a missing variable and is far harder to notice, because no coverage report records that two fields were correlated. And a second bench defect — reading a combinational output before it settled — produced 46 failures on a correct design, which is the kind of result that invites weakening a check instead of fixing a race.

14. What Comes Next

Data has moved, or a wLength of zero meant none would. Chapter 13.3 is the stage that closes the transfer, and it is the smallest and strangest of the three.

It carries no data — a zero-length packet, always. And it runs in the opposite direction to the data stage, which means the bus turns around one more time, and means a transfer with no data stage has a status stage whose direction is fixed by a rule rather than derived from anything.

It is also the only place a device can report that a request failed after it had already been accepted — which is a narrower and more useful thing than it sounds.

Browse the full path on the USB tutorials index.