H4.5 APB Peripheral Verification

HardFixVerilator · serverReview the topic

Fix an APB test driver that ends each transfer when its plan expects, not when the bus says so.

Hardware context: APB control/status peripheral using the declared teaching subset. Qualify the driver, monitor and independent register model against APB peripheral mutations.

An APB test environment passed on a good peripheral. Against a peripheral that never raises PREADY, its driver still counted every transfer as complete. No transfer timed out, and the command counts at the end were wrong.

The environment has two classes. apb_driver plays a list of commands onto the bus. Each command is a setup, then access edges until the transfer ends. A gap or a planned reset may follow. register_checker watches the bus and keeps a model of the registers. The checker is complete and correct.

The tests run the pair on a correct peripheral and on eleven faulty ones. They compare every pin and every checker report on every edge.

Find the bug in the driver and fix it.

Signals in the Timeline

SignalWidthRole
command_count5input of each check
outside_noise1input of each check
hardware_fault4input of each check
Full specification
The driver (keep these names and methods)
typedef struct packed { bit write; bit [7:0] address; bit [31:0] data; bit [3:0] strobe; bit deny;
                       int waits, gap, abort_after; } apb_command;
class apb_driver;
  apb_command commands[$];
  int index = 0, phase = 1, accesses = 0, gaps = 0, completed = 0, canceled = 0, timeouts = 0;
  function new(input apb_command supplied[$]);
  function void drive(input int cycle, output bit resetn, output apb_request request, output int waits);
  function void observe(input apb_sample sampled);
endclass
Driver ruleMeaning
drive()Called before each edge. It sets resetn, the request and wait_cycles for that edge.
SetupOne edge with PSEL = 1, PENABLE = 0 and the command's fields.
AccessPENABLE = 1 with the same fields. The command ends at the first access edge with PREADY = 1, error or not.
Planned resetabort_after = 0 resets right after the setup. abort_after = n > 0 resets after n access edges without PREADY.
WatchdogAfter more than waits + 2 access edges without PREADY, reset and add 1 to timeouts.
After a commandgap idle edges follow, then the next setup. With gap = 0 the next setup follows at once, PSEL still 1.
observe()Called after each edge with the sampled pins. It moves the driver to its next phase.
Idle edgesPSEL = 0, with noise on the other request pins.
The checker (given, complete and correct)
class register_checker;
  bit [7:0] control[4], status[4], events[4];   // byte models
  bit [31:0] write_count = 0;
  apb_request pending; bit active = 0;
  int expected_waits, waited, issued = 0, completed = 0, canceled = 0;
  int bad = 0, errors = 0, first_cycle = 255, first_kind = 0;
  function void sample(input int cycle, input apb_sample s);
  function string report();
endclass
EdgeWhat the checker does
ResetClear the register model. A pending transfer is canceled. Counters and error history survive.
SetupCopy the request and the wait count, and add 1 to issued. A setup while another transfer is pending is a PROTOCOL error and cancels it.
AccessThe request must match the setup copy, else PROTOCOL. Write data is compared only for writes. PREADY must equal waited >= expected_waits, else READY.
WaitAn access edge with PREADY = 0 adds 1 to waited.
CompletionPSLVERR must match the register map, else ERROR_FLAG. A good read must return the model value from before the edge, else READ_DATA. An error must return read data 0, else READ_DATA.
Model updateApply the bus effect only when the map allows the transfer, whatever PSLVERR showed. Then OR in status_set and event_set.
Every edgeirq after the edge must equal (STATUS | EVENTS) != 0 in the model, else IRQ.
Stray accessAn access with nothing pending is a PROTOCOL error. So is PSEL = 0 while a transfer is pending, which also cancels it.
KindValue
READY1
ERROR_FLAG2
READ_DATA4
IRQ8
PROTOCOL16

Each failed check adds 1 to errors and ORs its kind into bad. The edge and kind of the first failure are kept. With no failure they stay ff and 00.

The format of report(), printed after every edge
K=<bad>:<first edge>:<first kind>|E=<errors>|N=<issued>,<completed>,<canceled>,<pending>|C=<CTRL>,<WRITE_COUNT>,<STATUS>,<EVENTS>;
AddressRegisterBehaviour
00CTRLRead and write. Only bytes whose strobe bit is 1 change.
04WRITE_COUNTRead only. Adds 1 for each successful write to CTRL, even with all strobes 0.
08STATUSWrite 1 to clear (W1C). Each 1 bit in a strobed byte of the write data clears that bit.
0cEVENTSRead only and read to clear. A successful read returns the value, then clears the whole word.
10IDRead only. Always reads c001c0de.
ErrorAny other address, a write to a read-only word, or deny = 1. PSLVERR = 1, read data 0 and no register change.
RuleMeaning
Event inputsstatus_set and event_set are 32-bit inputs. They are sampled on every edge, also on idle, wait and error edges.
Order on one edgeFirst the bus effect of a completing transfer. Then status_set is ORed into STATUS and event_set into EVENTS.
Same-edge set and clearA hardware set wins over a bus clear on the same edge.
Read to clearA read of EVENTS returns the value from before the edge. The clear and any new event happen on that edge.
Resetresetn is active low and synchronous. It clears all four writable words, drops events and cancels the transfer in flight.
irqirq = 1 when STATUS or EVENTS is not 0 after the edge.
APB ruleMeaning here
SamplingEvery pin is sampled just before the rising edge of the clock.
SetupThe first edge of a transfer has PSEL = 1 and PENABLE = 0.
AccessThe edges after the setup have PSEL = 1 and PENABLE = 1.
CompletionA transfer ends at the one edge where PSEL, PENABLE and PREADY are all 1.
WaitAn access edge with PREADY = 0 is a wait. The request stays the same.
Back to backA new transfer may follow with PSEL still 1. It always starts with its own setup edge.
Ignored pinsPREADY outside an access and PSLVERR outside a completion mean nothing. Some tests drive noise on them.
SourceArm IHI 0024E, sections 3.1 to 3.4 and 4.1. This is a 32-bit subset with one completer and byte strobes.
Wait ruleMeaning
wait_cyclesThe test sets it for each transfer, from 0 to 3. The peripheral captures it at the setup edge.
TimingPREADY stays 0 for exactly wait_cycles access edges. The next access edge completes.
Zero waitsThe transfer still takes two edges: the setup, then one access.
Faulty peripheralWhat is wrong
1Side effects happen on wait edges too.
2Error transfers still change registers.
3A W1C or read-clear loses a hardware set from the same edge.
4Address bits above bit 4 are ignored, so address 20 aliases CTRL.
5Strobes are ignored.
6Reset does not clear the registers.
7PREADY comes one wait early.
8PSLVERR is inverted at completion.
9Bit 0 of read data is flipped.
10WRITE_COUNT adds 2 per CTRL write.
11PREADY never rises.
Part of a transcript rowMeaning
C12Edge number, counting from 0.
N1resetn.
S111PSEL, PENABLE and PWRITE.
00:11223344:f:0Address, write data, strobes and deny, in hex.
W2wait_cycles for this transfer.
R10:a5a50000PREADY, PSLVERR and read data, sampled before the edge.
I01irq before and after the edge.
K=00:ff:00|E=0|...Your report() after this edge.
END=1,3,0,0At the end: all commands done, completed, canceled and timed out.

Each test runs 64 edges and builds a text transcript, one row per edge. Your transcript is compared with the expected one as a whole. The result shows both lengths and exact_equal. Equal lengths alone do not pass.

Examples

Example 1

A Same-Edge Event Survives W1C
Input
Correct peripheral. Clear STATUS bit 0 with 2 waits, read STATUS, try a denied clear of STATUS with 2 waits, read STATUS. STATUS bit 0 is set at edges 0 and 3, bit 8 at edge 6.
Output
actual_length = 7105, expected_length = 7105, exact_equal = yes

The clear completes at edge 3, the edge that sets bit 0 again, so the bit stays set. The read at edge 5 returns 00000001. The denied clear changes nothing, and the last read returns 00000101. No error is logged.

Example 2

Early Read-Clear During Waits
Input
Faulty peripheral 1. Read EVENTS three times with 3 waits, the third with deny = 1, then read EVENTS again. EVENTS gets 3 at edge 0, 4 at edge 4 and 80 at edge 10.
Output
actual_length = 7105, expected_length = 7105, exact_equal = yes

The fault clears EVENTS on the first wait edge, so irq falls at edge 1. The model still holds 3, so the IRQ check fires first: first edge 01, kind 08. At edge 4 the read returns 0 instead of 3, so bad becomes 0c.

Example 3

Every Transfer Times Out
Input
Faulty peripheral 11. Write 1 to STATUS with 1 wait, read STATUS, try a denied write of STATUS with 1 wait, read STATUS.
Output
actual_length = 7151, expected_length = 7151, exact_equal = yes

PREADY never rises, so the checker logs a READY error at edge 2: first edge 02, kind 01. The driver keeps the write on the bus. After four stalled access edges, the watchdog resets at edge 5. Each later command times out the same way. The line ends END=1,0,4,4: nothing completed, and all four commands timed out. The buggy driver ends the write after edge 2, so its pins differ from edge 3 on.

Constraints and Contract

  • The driver must never change a request in the middle of a transfer. Only a completion or a reset ends one.
  • Keep the class names, the fields, the method signatures and the report() format.
  • The first two examples are the first two tests. The third example is a test with peripheral 11. All tests use the same timing and register rules.

Hints

Hint 1

Follow a test with peripheral 11, which never raises PREADY. How should each transfer end, and how does this driver end it?

Hint 2

The command says how many waits to expect. The bus says when a transfer really ends. Which one must the driver follow?

Hint 3

In observe(), the access branch ends a command when accesses > waits. It must end it only when sampled.ready is 1.

What the grader checks: The driver and checker run against a real clocked peripheral, correct or with one of eleven faults. Every pin, every checker report and the final command counts are compared. APB5 extensions and electrical timing are out of scope.

83 checks on Verilator · server. Run the examples first, then check the full regression. Full checks use the server judge. Downloads contain public samples only. A passing result establishes the tested cases, not a proof for all possible inputs.

See all 7 steps and the final capstone

Report a problem with this page

Your code SystemVerilogSaved locally
Ln 1, Col 1Tab indents · Ctrl/⌘ + Enter runs samples
Not run yet

A Same-Edge Event Survives W1C

Input
Correct peripheral. Clear STATUS bit 0 with 2 waits, read STATUS, try a denied clear of STATUS with 2 waits, read STATUS. STATUS bit 0 is set at edges 0 and 3, bit 8 at edge 6.
Expected output
actual_length = 7105, expected_length = 7105, exact_equal = yes

The clear completes at edge 3, the edge that sets bit 0 again, so the bit stays set. The read at edge 5 returns 00000001. The denied clear changes nothing, and the last read returns 00000101. No error is logged.

Run samples executes all 3 public checks. Check all tests runs 83 checks on the server.

Verilator · server