Wishbone UART-Based Debug Bridge

Motivation

This repo provides a drop-in debug master for a Wishbone B4 bus (pipelined mode) that can be accessed over UART from a program running on a host machine or in a testbench harness.

Connection Interface

The module that must be integrated into a design to connect this debug bus interface is the wbdbgbus module. Following are the parameters and connections required to integrate this module:

// Configuration parameters
parameter CLK_FREQ // Clock frequency, used for UART
parameter UART_BAUD // UART baud rate
parameter DROP_CLKS // Number of clocks before dropping an unfinished command
parameter FIFO_DEPTH // Depth of FIFO used for commands / responses

// Module Connections

// UART
output o_tx
input i_rx

// Wishbone
output o_wb_cyc
output o_wb_stb
output o_wb_we
output [31:0] o_wb_addr
output [31:0] o_wb_data
input i_wb_ack
input i_wb_err
input i_wb_stall
input [31:0] i_wb_data

// Interrupts
input i_interrupt_1
input i_interrupt_2
input i_interrupt_3
input i_interrupt_4

// Clock
input i_clk

Interacting with the bus

Python Library

The easiest way to interact with the debug bus is through the provided Python library. This library is located in the host-library subdirectory of this repo, and its documentation can be found in host-library/README.md. If using the library, the remainder of this section may be disregarded.

Communication Protocol

A host machine interacts with the bus through a fairly simple protocol defined here.

Flow Control: As this is a debugging bus, the host process is responsible for managing flow control. The host process may choose to send a burst of instructions without waiting for acknowledgements, however the size of this burst must be limited to less than the size of the internal FIFO and this must be regulated by the host. If the difference between the number of sent instructions and the number of recieved acknowledgements is greater than the FIFO depth, additional instructions may be discarded.

To read a single word from the bus:

Send a "Set Address" instruction with the address to read
Wait for an "Address Acknowledge" response
Send a "Read Request" instruction
Wait for the "Read Response" response, which will contain the data that has been read

To read multiple sequential words from the bus:

Send a "Set Address (Auto-Increment)" instruction with the base address to read from
Wait for an "Address Acknowledge" response
Send a "Read Request" instruction
Wait for the "Read Response" response, which will contain the data that has been read
Repeat steps 3 and 4 for each consecutive address to read from. The address will automatically increment by 1 after each read.

To write a single word to the bus:

Send a "Set Address" instruction with the address to write to
Wait for an "Address Acknowledge" response
Send a "Write Request" instruction with the data to write
Wait for the "Write Acknowledge" response

To write multiple sequential words to the bus:

Send a "Set Address" instruction with the base address to write to
Wait for an "Address Acknowledge" response
Send a "Write Request" instruction with the data to write
Wait for the "Write Acknowledge" response
Repeat steps 3 and 4 for each consecutive address to write to. The address will automatically increment by 1 after each read.

To reset a hung bus:

Send a "Bus Reset" instruction. This will automatically bypass any other instructions or stalls and immediately reset the bus master.
Wait for a "Bus Reset Acknowledge" response. If one is not received, a power-cycle may be required.

Instruction Format

A simple 36-bit-wide binary data format is defined, consisting of a 4-bit opcode and 32-bits of data. When passing the data over a UART connection, it is converted into 5 bytes, with the first byte including 4-bits of don't-care and a 4-bit opcode, and the remaining 4 bytes containing the 32-bit data in big-endian format.

The command opcodes (binary) are defined as follows:

0001 - Read Request
0010 - Write Request (Data = data to write)
0011 - Set Address (Data = address to set)
0111 - Set Address w/ Auto-Increment (Data = base address to set)
1111 - Bus Reset

The response opcodes (binary) are defined as follows:

0001 - Read Response (Data = data read)
0010 - Write Acknowledge
0011 - Address Acknowledge
0100 - Bus Error
0101 - Bus Reset Acknowledge
1000 - Interrupt 1 Triggered
1001 - Interrupt 2 Triggered
1010 - Interrupt 3 Triggered
1011 - Interrupt 4 Triggered

Planned Features

Testbench interface wrappers

Contributing

Please file an issue if any bugs or missing features are found. Pull requests are always welcome.

License

MIT

asinghani/wbdbgbus