This script provides SPI protocol support for ScanaStudio logic analyzer software.

The main features of this script require absolutely no programming knowledge to be used. Some advanced features, like the SPI signal builder, requires some basic JavaScript knowledge to be used. The SPI script source code can be found here: spi.js. Please don't hesitate to comment and contribute!

Script capabilities

This script offer the following features:

• SPI protocol decoding (Including support for Dual/Quad IO SPI)
• SPI trigger sequence
• SPI signal builder
• Demo signal generator

Compatible logic analyzer devices

• SP209 series logic analyzers.
• SQ series (ScanaQuad) logic analyzers & pattern generators.
• ScanaPLUS (V1 and V2) logic analyzers.

SPI protocol decoding

To decode SPI signals, start by connecting you your Logic Analyzer device to to your SPI system, then configure the SPI decoder accordingly, ensuring that the channels selection matches the actual connection of the Logic Analyzer to the SPI lines.

Please click on "SPI Mode configuration" and "Advanced options" tab to further customize and adjust the SPI decoder.

The way words are displayed on the screen can be changed by clicking on the "Output format" tab.

Dual/Quad SPI

This SPI protocol decoder can be used to analyze Dual and Quad IO SPI transactions (Also called multi-IO). This mode can be configured using the "Dual/Quad SPI configuration" tab as shown in the picture below:

Decoded multi-IO words will be displayed on the CS channel as shown in the image below.

Notice that regular MOSI/MISO words will still be displayed regardless of the multi-IO mode chosen. The reason for this is that most SPI devices uses a mix of regular MOSI/MISO transactions and Multi-IO transactions. It's up to the user (or the high-level script using this one) to make sense of the decoded words.

SPI trigger sequence

To use the SPI trigger, one must first add and configure an SPI decoder to the ScanaStudio workspace. Since the SPI trigger relies on the configuration of the SPI decoder, we recommend that the user checks that valid SPI frames are decoded before attempting to configure the SPI trigger.

Once the SPI decoder is added to the workspace and correctly configured, you can add SPI trigger by going to Trigger > Edit trigger > SPI. The SPI trigger should look like the image below:

Simply click on one of the tabs to choose a trigger alternative (and configure it if needed), then click on "OK" to save your choices.

Trigger on any word

This trigger alternatives is used, as the name implies, to trigger when any valid SPI word is detected. That implies that correct CS (Chip Select) signals are detected, and at least one word of data was clocked. The number of clock cycles to consider a valid word depends on the decoder configuration (more precisely, the "bits per word" field).

Trigger on word value

This trigger alternative provides more control over the exact data word to be targeted by the trigger engine. To use this trigger, the exact word value must be given (in any format, whether it's decimal or hexadecimal) and the channel (MOSI or MISO) must be selected.

Also, it's mandatory to specify the order of that word in an SPI frame (that is, the order of the word after the active CS edge). The order is 0-based: the first word's order is "0".

Example SPI trigger

As an example, let's imagine we need to trigger on the second SPI MISO word in a frame having the value 0x2A. The trigger configuration would look like the image below:

Testing the trigger on arbitrary SPI signals shows the trigger being correctly detected (notice the trigger marker showing the exact SPI word).

SPI signal builder

This SPI script provides signal builder support, that is, it can be used from another script to easily build SPI frames.

⚠️ This feature is for advanced users, who are able to write (Java) scripts.

Importing and configuring the SPI signal builder

To import the SPI signal builder info your on_build_signals() functions, simply write:

var spi_builder = ScanaStudio.load_builder_object("spi.js")

Before the spi_builder object can be used, it must be correctly configured via the config() function:

spi_builder.config(ch_mosi,ch_miso,ch_clk,ch_cs,
                   bit_order,cpol,cpha,nbits,cspol,
                   sample_rate,clk_frequency)

Here is a full list of the parameters of this functions and their meaning:

Parameter	Description
ch_mosi	Index of the MOSI channel (0-based)
ch_miso	Index of the MISO channel (0-based)
ch_clk	Index of the Serial CLK channel (0-based)
ch_cs	Index of the CS (Chip select) channel (0-based)
bit_order	0 = MSB first, 0 = LSB first
cpol	Clock polarity (0 = clock LOW when inactive)
cpha	Clock phase (0 = Data samples on leading edge)
nbits	Number of bits per word
cspol	CS (chip select) polarity (0 = active low)
sample_rate	Device sampling rate (can be retrieved using ScanaStudio.builder_get_sample_rate()
clk_frequency	Frequency of the SPI serial clock line.

using the SPI signal builder

Once correctly configured, the SPI builder object offer the following functions:

put_silence(time_s)

This function can be used to generate samples - with the last known levels - for a given period of time (time_s). If this is the fist function to be called, then default idle states will be used as the "last known levels". In other words, this function can be used to "stretch" the last known logic state on the CS, MISO, MOSI and CLK lines.

This example generate idle state for 1 micro second:

spi_builder.put_silence(1e-6);

put_start()

This function generates a transition on CS going from idle to active state.

put_stop()

This function generates a transition on CS going from active to idle state.

put_word(mosi,miso)

This function simultaneously generates a word on MOSI and MISO lines. The words to be generated are given via the parameters of the function.

Examples

spi_builder.put_start();
spi_builder.put_silence(1e-6); //1 us
spi_builder.put_word(0xAA,0x55);
spi_builder.put_silence(1e-6); //1 us
spi_builder.put_stop();

For full and functional example usage of the SPI builder object, please take a look at the on_build_demo_signals() function in spi.js file. This functions uses the SPI signal builder object to generate random SPI transaction.

Another interesting example is the SPI Flash memory script which imports the SPI's builder object to build demo signals: spi_flash_memory.js

Licence

This document is distributed under the terms of the GNU General Public License GPLv3.

Copyright IKALOGIC SAS 2019