A simulation can't see the real flash chip, the real SD card or a board that only fails when it's warm. When the board shows a black screen, you need to look inside the running FPGA. An integrated logic analyzer (ILA) is a small recorder built into the design: it samples signals every clock and keeps the last few hundred, so you can read them out afterwards.
NandTier's ILA is hw/periph/nt_ila.v, at 0xC200_0000. On every rising edge of clk_sys it samples the CPU bus:
- SAMPLE0, the address, and SAMPLE1, the data: the write data for a store, the read data otherwise.
- SAMPLE2, eight flags: bit 0 ready, bit 1 valid, bits 5:2 the write strobes, bit 6 instruction fetch, bit 7 trap.
A ring buffer. Samples go into 128 slots and the write pointer wraps around, so once it's full the buffer always holds the latest 128 clocks. Reading back starts at the oldest: write READ_INDEX (0 = oldest), then read the three sample registers. A sample read takes one extra bus cycle, because the block RAM has to be read first.
A trigger. Writing CTRL bit 0 arms the ILA; bit 1 also enables the address trigger. A clock matches when a transfer completes (valid and ready) and (address ^ TRIGGER_ADDR) & TRIGGER_MASK is zero. After the match the ILA records POST_COUNT more clocks and stops. The rest of the buffer still holds what happened before the event. Without the trigger, it stops as soon as the buffer is full.
128 clocks is short. An instruction takes 4 clocks, a load or store 7, so the buffer holds about 25 instructions. A store to the UART while the transmitter is still busy waits thousands of clocks, and fills the whole buffer with one transfer. That's what the trigger is for: stop at the event, not at an arbitrary moment.
Two ways in. The CPU reaches the ILA's registers at 0xC200_0000 on every board. On the ULX3S, JTAG reaches the same registers (lesson 6.2), so you can read a trace even when the CPU is stuck in a trap.
What it costs. The 128 × 64-bit address and data samples live in block RAM. The 128 × 8 flag bits used to sit in 1,024 flip-flops, and reading one flag byte back out of them was a 128-to-1 multiplexer. That pushed the Tang Nano 9K past its size in the open flow (lesson 5.3) and put the multiplexer at the top of the timing report (lesson 6.8). Now each sample is one 72-bit block RAM word: address, data and the 8 flags, in the same two block RAMs, which had 8 bits spare. The 9K places again, at 65% of its LUTs.