SPI Protocol

The SPI protocol supports sending and receiving data over a Serial Peripheral Interface (SPI) connection.

Syntax

spi://hostname:port?option=value,... % Use SPI channel "port" with specified options
    

Description

The SPI protocol supports sending and receiving data over an SPI connection. It is identified by using spi as the protocol name in a URI. Appropriate hardware supporting SPI must be present on the system using the protocol.

The hostname in the URI is ignored, if specified. The port is an unsigned integer indicating which SPI port to use. Port 0 is the first SPI port in the system.

On Windows, the SPI protocol enumerates all the SPI devices currently present in the system and assigns port values to each SPI device. In this sense, the ports are "virtualized" since ports 0 and 1 may belong to one SPI card while port 2 may belong to another. The default port depends on the underlying SPI device. Refer to the documentation specific to each SPI device for the default value of this option (for example, refer to the spi-qpid protocol).

On the gumstix Linux Verdex target, the SPI port is built-in to the embedded processor, so no enumeration is necessary.

The options for the SPI protocol depend on the underlying device-specific SPI protocol used, but these options have been standardized for consistency. The options listed below are the standard options. Some of the options may not be available on some platforms.

The SPI protocol uses a master-slave paradigm. It is a synchronous protocol in which the master supplies the clock, often dubbed SCK, and the slave uses that clock. The master transmits data over the MOSI (master-out, slave-in) line at the same time as it receives data from the slave over the MISO (master-in, slave-out) line. Multiple slaves may be connected and are selected by the master using slave-select (SS) lines. However only one slave may transmit over the MISO line at a time, and each slave must tri-state its MISO line when its slave-select line is deasserted.

There are no read or write lines because the SPI protocol always sends and receives data at the same time over its full duplex connection. Whenever data is sent, the same amount of data is always received.

For example, the following sequence of operations is required to communicate over an SPI connection:

• send N bytes
• flush
• receive N bytes

Sending N bytes writes those bytes to the stream's send buffer. It may not flush the bytes to the underlying SPI communication channel. Hence, the flush is required to ensure that all the bytes were actually written to the SPI port.

When the N bytes are written to the SPI port, there will be N bytes that are automatically received at the same time and stored in the stream's receive buffer, even before the receive operation is performed!

Thus, when the receive operation is performed the data is already available in the receive buffer and the receive operation merely removes it from the buffer. No actual communication takes place during the receive operation.

A number of restrictions arise from this mode of operation. Firstly, data must always be sent before data can be received. It is not possible with the SPI protocol to simply receive data without sending data first. The Basic Stream blocks recognize protocols such as SPI that operate in this manner and handle the stream accordingly. Hence, the Basic Stream blocks may be used with the SPI protocol as may persistent streams.

For more sophisticated operations, the Intermediate Stream blocks may be used. The Stream Write-Read block is particularly useful because it combined a write followed by a read in a single operation, allowing the data that is always received by the SPI protocol to be consumed immediately, without the need for a separate block.

The baud rate used by the SPI master is determined by the baud option of the URI. A typical baud rate is 1MHz, although some devices can communicate much faster. For example, the verdex Verdex PRO can communicate at rates up to 13 MHz over its SPI connection.

The number of bits transferred during each send and receive operation is often programmable and is configured using the word option of the URI. Typical word lengths are 8 bits or 16 bits. The Quanser QPID card supports word lengths of 1 to 32 bits.

Data transmitted by QUARC over an SPI connection is not packed bit-wise. For example, if the word length is 12 bits then QUARC's SPI protocols take 16 bits at a time from the send buffer, transmits 12 bits and discards the remaining 4 bits. Hence, two 12-bit quantities are stored in 32 bits (4 bytes), not 24 bits (3 bytes).

This scheme makes it much easier to send and receive data over an SPI connection because no bit shifting and packing is required to prepare data to be sent, nor to to extract data received. Instead, standard data types may be used, even for word lengths other than 8, 16 or 32 bits.

For example, to send a series of 12-bit words, simply send a vector of 16-bit values (short integers) using the standard Stream API functions, such as stream_send_short_array. Twelve bits out of every 16-bit integer will be sent and 4 bits in each 16-bit integer will be left unused.

To receive a series of 12-bit words, simply receive a vector of 16-bit values (short integers) using the standard Stream API functions, such as stream_receive_short_array. The 12-bit quantities received will be sign-extended to 16 bits automatically.

The SPI protocol does not specify whether the most-significant bit (MSb) or least-significant bit (LSb) is transmitted or received first during an SPI transfer. Hence, most SPI devices allow this bit order to be configured. Use the lsb option in the URI to program the bit order of the SPI transfer. Set it to true to send and receive the LSb first. Omit the option or set it to false to send and receive the MSb first.

The polarity of the SCK clock is also generally configurable as either active-high or active-low and the phase of the clock may also typically be programmed. The phase determines the clock edge on which data is placed on the MISO or MOSI line, and the clock edge on which data is sampled. The following figure depicts the different configurations of clock polarity and phase.

The clock polarity is specified in the URI using the polarity option. The polarity is active-high by default. Set the polarity to one to make the clock active-low. Set it to zero or omit the option for an active-high SCK.

The clock phase is determined by the phase option in the URI. If the phase is zero (the default), then data is supplied by the SPI master on the MOSI line on the trailing/even edge of each clock pulse and data is sampled by the master from the MISO line on the leading/odd edge of the clock. Slave devices sample the MOSI line on the leading/odd edge. To ensure that data is available on the first clock edge, the master supplies data on the MOSI line before the first clock edge.

If the phase is one then data is supplied by the SPI master on the MOSI line on the leading/odd edge of each clock pulse and data is sampled by the master from the MISO line on the trailing/even edge of each clock pulse. Slave devices sample the MOSI line on the trailing/even edge.

The operation of the slave-select (SS) line for each slave varies. Most devices require that the SS line be asserted during each word transferred over an SPI connection. In this sense the SS line operates as a chip select signal.

However, some devices treat the SS line more as a frame signal. In this case, the SS line remains asserted during a series of word transfers and indicates the size of an entire frame or packet of data.

The SPI protocol supports two options for differentiating between these two uses of the SS line.

The slave option is employed when the SS line should be asserted for each word transferred. Its value is an integer indicating which slave-select line to assert during SPI transfers for this URI. Often, its value corresponds to a digital output on the SPI device providing the SPI services.

The frame option is used when the SS line should be asserted for an entire frame, rather than for each word transferred. Like the slave option, its value is an integer indicating which slave-select line to assert during SPI transfers for this URI. The size of a frame is determined by the amount of data sent at one time by the Stream API functions. The amount of data is determined by the Stream API functions or blocks invoked and the size of the stream's send buffer.

While this sounds complicated, it is actually quite easy. For example, if the following sequence of operations is performed:

• send N words
• flush
• receive N words

then the frame will consist of N words, presuming the stream's send buffer is large enough to contain all N words. Thus, the SS line will be asserted at the beginning of the entire transfer and not deasserted until all N words have been transferred.

Limitations

Performance

The performance of the SPI protocol depends on the performance of the underlying SPI device. Be sure to check the capabilities of your underlying hardware because maximum rates vary significantly. Rates of 1 MHz are typical. Signal integrity issues also affect the maximum baud rate achievable. For example, at high rates the capacitance of the lines can slow down the signals and limit the baud rate attainable.

Also note that the baud rate refers to the number of bits transferred per second and not the number of bytes. The number of bytes per second is usually less than 1/8th of the baud rate due to the overhead (albeit small) of the protocol. The word length also affects the performance. Longer word lengths generally yield better performance.

QUARC Target Manager

The SPI protocol cannot be used for communicating with the target (via a target URI) because the SPI protocol does not allow multiple connections on the same port. Hence, qc_set_default_model_uri cannot be used to set a default SPI protocol for models. Instead, the model URI must be specified explicitly in the Code Generation/Interface/MEX file arguments option of the Configuration Parameters of the model as well as the target URI.

Multiple client connections

The SPI protocol will only accept a single client connection at a time on a given port. It does not support time-division multiplexing of multiple client connections over a single SPI port because doing so would require adding a header to the information packets sent over the port. QUARC communication protocols never add extra information to the data sent over the communication channel in order to allow QUARC to communicate with user applications, sensors and other devices which would not support QUARC-specific data packets.

Options

mode

The mode option configures the SPI device providing SPI services as either a master or slave. Valid values for this option are "master" or "slave" accordingly.

memsize

The memsize option determines the size of the buffer (in bytes) used for SPI transfers. This size determines the maximum number of bytes that can be transferred in one operation. It is not the same as the Stream API's send and receive buffers but is used in interfacing with kernel drivers that implement the SPI protocol. The default buffer size depends on the underlying SPI device. Refer to the documentation specific to each SPI device for the default value of this option (for example, refer to the spi-qpid protocol).

On the gumstix Linux Verdex target the default buffer size is 1000 bytes.

baud

The baud option specifies the frequency of the SPI clock (SCK) in Hertz. For slave devices, the SPI clock rate is determined by the master, but it should still be configured, in case the rate is used to configure oversampling or filtering.

The baud rate determines the number of bits transferred per second, not the number of bytes. The default baud rate depends on the underlying SPI device. Refer to the documentation specific to each SPI device for the default value of this option (for example, refer to the spi-qpid protocol).

On the gumstix Linux Verdex target, the baud rate may vary from 6.3 kHz to 13 MHz inclusive.

word

This option indicates the word length used for SPI transfers. The word length is the number of bits involved in a single SPI transfer. It is typically 8 or 16 bits, but some devices require a different number of bits. For example, some analog-to-digital converters use 24-bit word lengths in which eight bits contain a register address and 16 bits contain the data to store in the converter's register.

The range of word lengths supported depends on the underlying hardware but is generally restricted to being between 1 and 32 bits. The word length is typically restricted to an even smaller range. Refer to the documentation specific to each SPI device for the default value of this option (for example, refer to the spi-qpid protocol).

On the gumstix Linux Verdex target, the word length may range from 4 to 32 bits inclusive.

lsb

This option determines whether the most-significant bit (MSb) or least-significant bit (LSb) is transmitted first. If this option is omitted then the MSb is transmitted and received first because that is typical of most devices.

Set this option to "true" or "1" to transmit (and receive) the LSb first. Set it to "false" or "0", or omit the option altogether, to transmit and receive the MSb first.

The gumstix Linux Verdex target does not currently support this option. It always uses the MSb first.

polarity

The polarity (CPOL) of the SPI clock (SCK) is configured using this option. The default polarity is active-high. Omit this option, or set it to "false" or "0" to program the clock polarity as active-high. Set the option to "true" or "1" for active-low clock polarity.

phase

The phase (CPHA) of the SPI clock (SCK) is programmed using this option. The default phase is trailing-edge phase. Omit this option, or set it to "false" or "0" to configure trailing-edge phase, in which data on the MOSI line is updated on the trailing edge of the SPI clock. For an active high SPI clock, the "trailing edge" is the falling edge of the clock. For an active low SPI clock, the "trailing edge" is the rising edge of the clock.

Set it to "true" or "1" for leading-edge phase, in which data on the MOSI line is updated on the leading edge of the SPI clock. For an active high SPI clock, the "leading edge" is the rising edge of the clock. For an active low SPI clock, the "leading edge" is the falling edge of the clock.

slave

The slave option determines the slave-select (SS) line used to select the SPI slave during each SPI transfer. It is an integer value identifying the SS line to be used. If the SS line delineates an entire frame of data rather than a single transfer, use the the frame option instead. If no SS line is required then simply omit the option. Refer to the documentation specific to each SPI device for details on the meaning of this option (for example, refer to the spi-qpid protocol).

frame

The frame option determines the slave-select (SS) line used to select the SPI slave during the transfer of entire frame. It is an integer value identifying the SS line to be used. If the SS line should be asserted for each word within a frame then use the slave option instead. If no SS line is required as a frame signal then simply omit the option. Refer to the documentation specific to each SPI device for details on the meaning of this option (for example, refer to the spi-qpid protocol).

Driver

The driver supporting the SPI protocol is called qrt_spi.

Targets

See Also

• QUARC SPI Gyroscope Demo
• QUARC SPI Gyroscope Mixed Types Demo
• QUARC SPI I/O Expander Demo
• QUARC SPI Multiple Devices Demo
• QUARC SPI Multiple I/O Expander Demo
• Stream Write-Read block
• Communications
• QUARC Communications Protocols
• MATLAB Stream Functions
• Communications Using the C Language

Copyright ©2024 Quanser Inc. This page was generated 2024-10-17. Submit feedback to Quanser about this page.

Link to this page.