Token Packets

Module 10 described four service contracts without touching a wire. Every one of them assumed something unexamined: that the host can name a destination before sending anything to it.

That naming is a packet, and it is the first one on the bus in every transaction.

1. Why a Token Exists at All

USB is a shared bus with one initiator. Chapter 10.1 §1 established that the host initiates every transaction; what it did not have to say is that every device on the bus sees every packet.

So a packet that carried only data would be ambiguous — several devices, several endpoints on each, and nothing to say which one it was for.

The token solves that by separating naming from carrying. A transaction opens with a small packet whose entire job is to say who and what kind, and only then does anything move.

Three facts follow directly, and each matters later:

• A device decides in the token whether the rest of the transaction concerns it at all. Chapter 8.4's device address is the field that decision reads.
• The direction is in the token, not in the data. Chapter 9.4 established that IN and OUT are named from the host's point of view; the token is where that name is actually transmitted.
• A corrupted token must be treated as no token. Acting on a damaged one means acting on the wrong endpoint, or on behalf of the wrong device.

2. What Is In a Token

A token packet is three fields after the PID, and it is small deliberately — it is transmitted before every single transaction, so its cost is paid constantly.

Seven bits of address gives 127 usable devices — address 0 is reserved, which Chapter 8.3 needed: a device that has not been assigned an address yet must still be reachable, and it is reachable at 0.

Four bits of endpoint gives 16 per direction, which is exactly Chapter 9.3's budget, and the reason that budget is what it is: the number came from the token's width, not from a judgement about how many endpoints a device needs.

3. The Four Token PIDs

The PID values are not arbitrary, and the structure in them is the subject of Chapter 11.5. What this chapter needs is the four low nibbles and what each means:

Every one of these low nibbles ends in 01. That is the token group, and Chapter 11.5 shows it is one of four such groups of exactly four — a structure that is provable from the values rather than asserted.

SETUP deserves a note now rather than later. It is a token, and what makes it special is not its shape but a rule attached to it: a device may not refuse a SETUP. Chapter 10.2 §1 established that control traffic is how a host manages a device it has not yet agreed anything with; a device that could decline the opening of that conversation could make itself unmanageable. Chapter 11.3 is where that rule has teeth.

4. Four Reasons to Ignore a Token

A device sees every token on its bus and acts on almost none of them. Being precise about why it ignores each one is the design, because each reason has a different consequence when it is missing.

1 — It is not addressed to this device. The common case by a wide margin. On a bus with several devices, most tokens name somebody else, and a device that answers them corrupts another device's transaction.

2 — The CRC failed. The eleven bits cannot be trusted, so neither the address nor the endpoint can. Silence is the only correct response — a device cannot report a corrupted token, because it does not know whether the report would be addressed to it either.

3 — The device is not in a state where it can be addressed. Chapter 8.3: below Default there is no shared understanding, and a device that answers before there is one answers on the basis of an address nobody assigned it.

4 — It is an SOF. Not addressed to anyone, and its eleven bits are not an address. §2's trap.

5. The Token Decoder, as RTL

// ─────────────────────────────────────────────────────────────────────────
// usb_token_decode
//
// Classification: SIMPLIFIED SYNTHESIZABLE TEACHING RTL. It models section
// 4's four filters and the extraction of what survives them.
//
// WHAT IT MODELS. The decision a device makes on every token it sees: is
// this for me, and if so, which endpoint and which direction?
//
// WHAT IT DOES NOT MODEL. The serial reception, framing and bit-unstuffing
// that produce `token_valid` (Module 14 owns signalling); the CRC5
// computation itself (Chapter 11.6 -- this block consumes the RESULT); the
// PID check field (Chapter 11.5 -- `pid` here is the low nibble, already
// validated); the data packet that follows (Chapter 11.2); the handshake
// that ends the transaction (Chapter 11.3); and the transaction sequencing
// that ties the three together (Module 12).
//
// ── ON COMBINATIONAL OUTPUTS ────────────────────────────────────────────
// Everything here is combinational, deliberately. A token's decode must be
// available in the same cycle its validity is, because the transaction that
// follows starts immediately -- there is no slack in which to register it.
// The block is a FILTER, not a state machine: it retains nothing, which is
// also why a bus reset needs no handling here. State lives in the blocks
// this one feeds.
// ─────────────────────────────────────────────────────────────────────────
module usb_token_decode (
  input  logic        clk,
  input  logic        rst_n,

  // A token packet has been received and framed. Module 14's business.
  input  logic        token_valid,

  // The PID's low nibble. The check field (Chapter 11.5) has already been
  // verified -- a PID that failed it never reaches here.
  input  logic [3:0]  pid,

  // The eleven bits between the PID and the CRC. What they MEAN depends on
  // the PID, which is section 2's trap and this block's most important line.
  input  logic [10:0] token_field,

  // Chapter 11.6's verdict on those eleven bits.
  input  logic        crc5_ok,

  // Chapter 8.4: the address this device currently answers to. Zero while
  // the device is in Default (Chapter 8.3), which is how an unenumerated
  // device is reachable at all.
  input  logic [6:0]  dev_address,

  // Chapter 8.3: at least Default. Below it there is no agreement under
  // which an address means anything.
  input  logic        dev_addressable,

  output logic        accept,        // this transaction is ours
  output logic [3:0]  endp,
  output logic        is_setup,
  output logic        is_in,
  output logic        is_out,
  output logic        is_sof,
  output logic [10:0] frame_number   // meaningful ONLY when is_sof
);

  // Section 3. Low nibbles; the full bytes are in Chapter 11.5.
  localparam logic [3:0] PID_OUT   = 4'b0001;
  localparam logic [3:0] PID_IN    = 4'b1001;
  localparam logic [3:0] PID_SOF   = 4'b0101;
  localparam logic [3:0] PID_SETUP = 4'b1101;

  assign is_out   = token_valid && (pid == PID_OUT);
  assign is_in    = token_valid && (pid == PID_IN);
  assign is_setup = token_valid && (pid == PID_SETUP);
  assign is_sof   = token_valid && (pid == PID_SOF);

  // ── THE LINE THAT MATTERS MOST ──────────────────────────────────────────
  // SOF is a token and is NOT in this list. Its eleven bits are a frame
  // number, and reading them as an address means a device whose address
  // happens to equal the low seven bits of the current frame number will
  // answer a packet addressed to nobody. Section 6 measures it.
  logic addressed_token;
  assign addressed_token = is_out || is_in || is_setup;

  // Both readings of the same eleven bits are exposed; which one is valid is
  // told by `is_sof`. They are NOT gated against each other, because gating
  // would hide the very confusion this block exists to prevent -- a consumer
  // that reads `endp` on an SOF has a bug, and it should be ITS bug.
  assign endp         = token_field[10:7];
  assign frame_number = token_field;

  // Section 4's four filters, in one expression so that no reading of this
  // block can miss one of them.
  assign accept = addressed_token          // 4: not an SOF, and a real token
                  && crc5_ok               // 2: the eleven bits are trustworthy
                  && dev_addressable       // 3: there is an agreement to act under
                  && (token_field[6:0] == dev_address);  // 1: it is for us

endmodule

What it models. The per-token accept/ignore decision and the extraction of endpoint and direction from an accepted one.

Engineering reason. Because it is the point at which a device commits to participating in a transaction, and every way of getting it wrong is either invisible or catastrophic.

Inputs. Token validity, the PID's low nibble, the eleven-bit field, the CRC verdict, and two facts about the device itself — its address and whether it may be addressed at all.

State retained. None. The block is a filter; clk and rst_n are present for the properties in §7 and for consistency with the blocks it feeds, not because anything is stored.

Outputs. An accept indication with the selected endpoint, four token-type flags, and the frame number — the last valid only when is_sof.

Hardware implied. Four 4-bit comparators, one 7-bit comparator, and a four-input AND. Tens of gates.

Reset behaviour. Nothing to reset. The device state that does need resetting lives in Chapter 8.3's FSM, which drives dev_address and dev_addressable.

Assumptions. That token_valid is asserted only for a fully-received, correctly-framed token; that pid has already passed Chapter 11.5's check field; that crc5_ok refers to these eleven bits; and that dev_address and dev_addressable are stable for the duration of the token.

Omissions. Everything in the header — and the list is long because a block named token decode invites being read as a receiver.

What DV should verify. That no token is accepted with a failed CRC; that no token addressed elsewhere is accepted; that no token is accepted while the device is not addressable; that an SOF is never accepted as an addressed token; that the endpoint is extracted from the correct four bits; and that the three type flags are mutually exclusive.

6. Mutation Test

Five mutations, measured over 4,010 tokens in two deliberately different stimulus plans. The difference between the plans is the finding, so the plans come first:

• Plan A — 2,010 tokens, unconstrained random. Address, endpoint, PID, CRC verdict and device state all independent and uniform. This is what randomise everything produces.
• Plan B — plan A plus 2,000 more in which the address is constrained to match this device roughly half the time.

In plan A, only 30 of 2,010 tokens carried this device's address, and only 7 were accepted. Plan B brought that to 155 accepted.

Four of the five hang on a handful of events in plan A, and the reason is arithmetic rather than bad luck: every one of them is gated behind an address match, which unconstrained random stimulus produces once in 128. §8 is about what follows.

T1 — drop the CRC check

Measured: 1 escape in plan A, 23 across both.

The device acts on eleven bits it has been told are unreliable. And the consequence is not a failed transaction — it is a successful one, for the wrong endpoint. A corrupted ENDP field that still lands on a valid endpoint number produces a transaction that completes normally and moves data to the wrong place.

A CRC that is computed and then not consulted is worse than no CRC, because the cost was paid and the protection was not taken.

T2 — drop the address check

Measured: 294 escapes in plan A alone — by far the loudest of the five.

And that number is misleading in the most instructive way. It is large because the bench had other devices' tokens in it. §4's callout is the point: on a single-device bus this mutation produces zero symptoms, because every token really is for this device. It becomes a defect only when something else is attached.

The escape count here is a property of the stimulus, not of the design.

T3 — extract the endpoint from the wrong four bits

assign endp = token_field[9:6];   // MUTANT T3: off by one

Measured: 6 escapes in plan A, 145 across both.

The plan A number understates it drastically, and for a reason worth internalising: the endpoint can only be checked on a token that was accepted, and plan A accepted seven. The mutation was wrong on essentially every accepted token — 145 of the 155 — but the bench only reached 155 of them after the address was constrained.

This is a defect with a 100% failure rate that a bench can still almost entirely miss.

T4 — drop the addressable-state check

Measured: 2 escapes in plan A, 27 across both.

A device answers before there is an agreement under which its address means anything. Chapter 8.3 established that below Default the device and host share no understanding — so the address being compared against was not assigned by anybody.

The practical symptom is enumeration failure that depends on what else is on the bus, which is among the least tractable classes of USB bug.

T5 — treat SOF as an addressed token

Measured: 3 escapes in plan A, 51 across both.

§2's trap, realised. The SOF's eleven bits are a frame number; read as ADDR and ENDP, frame number 5 is address 5, endpoint 0.

And the symptom is periodic. Frame numbers increment and wrap, so a device at address N collides with the SOF once every time the frame counter's low seven bits come around — once every 128 frames, which at full speed is once every 128 ms, forever, with metronomic regularity.

7. The Assertions

// ─────────────────────────────────────────────────────────────────────────
// Classification: TEACHING ASSERTIONS about the token filter.
// N-properties are the NEGATIVE space: what must never be accepted.
// Every one of section 6's mutations violates exactly one of them, which is
// the shape a filter's property set should have.
// ─────────────────────────────────────────────────────────────────────────

// N1 -- NEVER ON A BAD CRC. Section 6's T1.
property p_no_accept_bad_crc;
  @(posedge clk) disable iff (!rst_n)
    accept |-> crc5_ok;
endproperty
assert property (p_no_accept_bad_crc);

// N2 -- NEVER SOMEBODY ELSE'S. Section 6's T2.
property p_no_accept_foreign;
  @(posedge clk) disable iff (!rst_n)
    accept |-> (token_field[6:0] == dev_address);
endproperty
assert property (p_no_accept_foreign);

// N3 -- NEVER BEFORE THERE IS AN AGREEMENT. Section 6's T4.
property p_no_accept_unaddressable;
  @(posedge clk) disable iff (!rst_n)
    accept |-> dev_addressable;
endproperty
assert property (p_no_accept_unaddressable);

// N4 -- NEVER AN SOF. Section 6's T5, and the only property here whose
// justification is not visible at the point of use: it is stated because
// SOF's eleven bits are a frame number, which is a fact about the PACKET
// FORMAT rather than about this block.
property p_no_accept_sof;
  @(posedge clk) disable iff (!rst_n)
    is_sof |-> !accept;
endproperty
assert property (p_no_accept_sof);

// ── And the positive half, without which the four above are satisfied by a
//    device that accepts nothing at all. Chapter 9.5 measured what happens
//    when only the negative half of such a pair is written: nothing fires.
// P1 -- ACCEPT WHEN ALL FOUR HOLD. Written as an EQUIVALENCE so that it
// cannot be satisfied by a design that is merely conservative.
property p_accept_iff;
  @(posedge clk) disable iff (!rst_n)
    accept == ((is_out || is_in || is_setup) && crc5_ok && dev_addressable
               && (token_field[6:0] == dev_address));
endproperty
assert property (p_accept_iff);

// S1 -- THE TYPE FLAGS ARE MUTUALLY EXCLUSIVE. A token is one thing.
property p_type_onehot0;
  @(posedge clk) disable iff (!rst_n)
    $onehot0({is_out, is_in, is_setup, is_sof});
endproperty
assert property (p_type_onehot0);

// E1 -- THE ENDPOINT COMES FROM THE TOP FOUR BITS. Section 6's T3. This
// looks like a restatement of the RTL and is not quite: it is a statement
// about WHICH BITS, sourced from the packet format rather than from the
// implementation, and it is the only thing standing between the design and
// an off-by-one nobody can see.
property p_endp_slice;
  @(posedge clk) disable iff (!rst_n)
    accept |-> (endp == token_field[10:7]);
endproperty
assert property (p_endp_slice);

P1 is the property that makes the rest safe. N1 to N4 are all implications with accept in the antecedent, and a design that ties accept low satisfies every one of them — Chapter 9.5 measured that exact shape of hole. Writing the acceptance condition once as an equivalence closes it.

E1 deserves its scepticism. A property that restates an assignment is usually worthless. This one is not, because the assignment encodes a fact about the packet format — that ENDP is the top four of the eleven — and the property is where that fact gets written down independently of the code that implements it. If both are wrong in the same way, nothing is gained; the value is that they are sourced differently.

8. Verification

This chapter's commit point is the device joined exactly the transactions that were its own.

Stimulus. Directed tokens for each of the four PIDs; a token for another device; a failed CRC; a token while not addressable; an SOF whose frame number's low seven bits equal this device's address — the case T5 needs, and one no randomiser will produce often; a non-token PID; the default address 0 during enumeration, because that is the one time every device on the bus shares an address; and both randomised plans.

Observation. The accept decision, the extracted endpoint, and the type flags — every token, against an independently written reference model that recomputes the four conditions from §4 rather than from the RTL.

Reference model. Four lines. Its value is entirely in being written from the filter rules — in particular, its list of addressed tokens is derived from SOF is not addressed to anybody, which is why it diverges on T5 rather than reproducing it.

Coverage — crosses:

• PID × CRC verdict × addressable × address-match — all 32 combinations of the last four, with each of the four token PIDs
• endpoint number 0 to 15 × each addressed token type
• address 0 (default) × every device state
• SOF frame number whose low 7 bits equal dev_address — a directed cross, because it will not happen otherwise
• non-token PIDs presented with token_valid asserted

Negative cases with defined outcomes: nothing accepted on a bad CRC; nothing accepted for another address; nothing accepted while unaddressable; no SOF ever accepted; and no type flag asserted while token_valid is low.

9. Debugging: the Device That Glitches Every 128 Milliseconds

A device works. Once every roughly 128 ms it produces a spurious transaction — a stray IN response, a corrupted endpoint access. The interval is metronomic. Swapping cables, hubs and hosts changes nothing.

What does metronomic tell you? That it is locked to something that counts. Cables, noise and thermal effects do not keep time; counters do.

What counts on a USB bus? The frame number, incrementing once per frame and carried in an SOF — Chapter 11.4. At full speed a frame is 1 ms, so a 7-bit field of it wraps every 128 ms.

Which immediately suggests where to look, and the suggestion is unusually specific: something is reading seven bits of the frame number as though they were an address.

How do you confirm it without instrumenting the device? Change the device's address. If the period stays at 128 ms but the phase moves, the address is being compared against the frame number — because the collision happens when the counter passes your address, and moving your address moves when that is.

What would a protocol analyser show? A perfectly normal SOF, followed by a device transmitting when it was not asked to. The SOF is not the anomaly; the response to it is — and a trace filtered to this device's traffic will typically hide the SOF entirely, because the SOF is not addressed to this device and the filter knows it.

The signature to keep: a fault whose period is a power of two multiplied by the frame time is a frame-counter aliasing bug — and the exponent tells you how many bits of the counter are being misread.

10. Common Misconceptions

11. Reason It Through

Two identical devices from the same vendor work perfectly on their own. Attached to the same hub, both become unreliable — and unplugging either one fixes the other.

What does unplugging either fixes the other tell you? That the relationship is symmetric. That rules out a great deal: it is not one device being a bad citizen and the other a victim, because either role can be removed to cure the pair.

What is symmetric about two identical devices? Everything except the address the host assigned them — and by Chapter 8.4, those are necessarily different.

So if the addresses differ, how can they collide? They can only collide if the address is not actually being used. §6's T2: a device that skips the address comparison answers every addressed token on the bus. Two such devices answer each other's tokens, symmetrically, and each is broken by the other's presence.

Why did this ship? Because the vendor tested with one device. §4's callout, arriving as a warranty claim: too-loose filtering has no symptom until there is a second device, and a single-device bench cannot produce one.

Could it be something else? Two candidates, and both are distinguishable:

• Address assignment failed and the host gave both the same address. Testable — read the addresses. It would also be a host bug, and would reproduce with two devices from different vendors.
• A power problem on the hub. Would not be cured by unplugging either device specifically; would track total current, and would not be symmetric between two devices of different power draw.

And the transferable point: a symmetric fault between two instances of the same design points at something the design shares and the instances were supposed to differentiate. The address is exactly that — and a device that does not use it has thrown away the only thing making it distinct.

12. Understanding Check

13. Summary

A token names a destination before anything is sent to it, which is what a shared bus with one initiator requires. It carries a PID, 7 bits of address, 4 bits of endpoint and a CRC5 — and the endpoint budget of Chapter 9.3 is those four bits rather than a judgement about what devices need.

ADDR and ENDP are one eleven-bit field with a convention applied, protected jointly by five bits of CRC. And the SOF token uses the same eleven bits as a frame number, with only the PID to say so — which is the module's first genuinely dangerous piece of aliasing.

A device ignores a token for four distinct reasons, three of which produce silence: not mine, CRC failed, not yet addressable, and it is an SOF. The filtering asymmetry is the practical lesson — too strict is loud and gets found; too loose works perfectly until a second device exists.

§6 measured five mutations across two stimulus plans:

• Skipping the CRC check produces successful transactions on the wrong endpoint — a CRC computed and not consulted is worse than none.
• Skipping the address check escaped 294 times because the bench had other devices in it, and would have escaped zero times on a single-device bus.
• An off-by-one endpoint slice was wrong on 145 of 155 accepted tokens — a 100% failure rate that the unconstrained plan still nearly missed.
• Skipping the state check produces enumeration failures that depend on what else is attached.
• Treating SOF as addressed removes nothing and adds a correct-looking entry to a correctly-named list — it survives review, and its symptom is a glitch every 128 frames on a device that otherwise works.

And §8 is the module's first hard verification finding: four of the five defects sit behind a 7-bit comparator that unconstrained random stimulus matches once in 128. Two thousand fully randomised tokens produced seven accepts. More stimulus does not fix that ratio — constraint does, and the constraint to apply is the one that makes a real bus's view reachable. Ask of any bench with a comparator in it: how often does it match, and is that on purpose?

14. What Comes Next

The token named a destination. The next packet carries something to it — and immediately raises a question the token never had to answer.

Chapter 11.2 is Data Packets, and its subject is not the payload. It is DATA0 and DATA1: two PIDs that carry identical data and differ only in a single alternating bit. That bit exists to answer one question — is this the packet I was expecting, or the one I already have? — and the machinery that maintains it is the most frequently mis-implemented state in USB, because it must be updated on an event that the device can fail to observe.

Browse the full path on the USB tutorials index.