When we are going through the pain which is integration, one of the most useful elements we can include in the design is an Integrated Logic Analyser (ILA).
ILAs allow us to examine signals internal to the FPGA and monitor its behavior. This can be very useful when we have a tricky issue to find that is difficult or time consuming in simulation.
For many debugging applications, the ILA’s basic triggering function such as the ability to trigger on a signal’s level, edge, or value will be sufficient.
However for more in-depth debugging, more complex triggering is required.
A good example of this is counting the number of lines in an image being received. Expanding upon this example further, and assuming the video signal of interest consists of a frame and line valid signals along with the pixel data.
To count the total number of lines, initially we want to detect the assertion of the frame valid signal. The rising edge of the frame valid signal, of course, indicates the start of a new frame. Following detection of the start of frame, we want to count the number of times the line valid signal has a rising edge as this indicates the start of a new line.
Counting the number of rising edges on the line valid between the rising and falling edges of frame valid will report the number of lines in the frame.
We can configure the ILA to do just this using the Trigger State Machine.
To be able to use the Trigger State Machine (TSM) in an ILA, we need to enable the Advanced Trigger option in the ILA configuration.
Enabling the advanced trigger also provides access to four 16-bit counters and four flags. We can use these in the trigger state machine to count events and indicate progress; in fact, both features are very useful.
The trigger state machine is described using a simple scripting language. This allows us to declare and change states and branch to states depending upon Signal or ILA counter values.
The structure of the simplest TSM script would be:
Although, this would not do much apart from run an immediate trigger.
Instead, we want to use the status of signals in the ILA and counters to progress through states before we trigger the ILA.
We can define up to 16 states in our trigger state machine, and in each state we can use branching (if else) to determine the next action to take. To transition between states, we use the goto command. The goto or trigger statement must be the last thing we call in a state or a branch.
There is more syntax than I can cover in one blog; however, the language templates within Vivado provide a significant resource on both usage and syntax.
We can write the Trigger State Machine script using any text editor — the file extension should be .tsm.
Once the project with the ILA has been built and we have our TSM script ready to go, the next step is to program the device and open Vivado’s hardware manager.
To use the TSM script, we need to change the trigger mode from BASIC to ADVANCED_ONLY in the ILA settings tab.
It is within this tab that we can also select the TSM file we wish to use with ILA.
But before we can use the TSM script, we should check that it is OK and contains no errors.
To do this on the status tab in the ILA, we need to click on the compile TSM button. This will compile the TSM script and open a dialog if there any errors.
If we do not do this, when we click on trigger it will be compiled for the first time.
The TSM also provides access to four flags in the ILA, which can be set by the script to indicate progress as the script is run. We can even use them to indicate the results of comparisons etc such as counter values.
To check the number of lines in the imager during the frame valid period, I developed the script below. It shows a good example of how we can use the flags to convey information as well.
In the first state (wait_fs_re), the script waits until the rising edge of the frame sync is detected. Upon detecting this, it clears the counter and resets the flags and moves on to the next state.
While in the second state (wait_fs_fe), the script counts the rising edges which occur on the line valid signal. Each time a rising edge is detected on the line valid, a counter is incremented. When the falling edge of the frame sync is detected, the final state is entered.
It is in the final state that the counter value is checked. This is checked against the expected number of lines 800 or 0x320. If the correct number of lines are received, flag 1 is set. Alternatively, if the number of lines is different to that expected, flag 3 is asserted.
Of course, we can use TSM to filter information too — for example, monitoring an Ethernet input for a specific packet format, triggering only when that is received.
The ability provided by the enabling the ILA’s TSM provides a flexibly during debug that can often save the time taken to write a simple test functions.