Hardware Interfaces

Referring to the Comportable guideline for peripheral device functionality, the module spi_host has the following hardware interfaces defined

  • Primary Clock: clk_i
  • Other Clocks: none
  • Bus Device Interfaces (TL-UL): tl
  • Bus Host Interfaces (TL-UL): none

Peripheral Pins for Chip IO

Pin nameDirectionDescription
sckoutputSPI Clock
csboutputChip Select# (One hot, active low). The size of this port should match NumCS.
sd[3:0]inoutSPI data bus

Inter-Module Signals

Port NamePackage::StructTypeActWidthDescription
passthroughspi_device_pkg::passthroughreq_rsprsp1
tltlul_pkg::tlreq_rsprsp1

Interrupts

Interrupt NameTypeDescription
errorEventError-related interrupts, see ERROR_ENABLE register for more information.
spi_eventEventEvent-related interrupts, see EVENT_ENABLE register for more information.

Security Alerts

Alert NameDescription
fatal_faultThis fatal alert is triggered when a fatal TL-UL bus integrity fault is detected.

Security Countermeasures

Countermeasure IDDescription
SPI_HOST.BUS.INTEGRITYEnd-to-end bus integrity scheme.

Registers

Summary

NameOffsetLengthDescription
spi_host.INTR_STATE0x04Interrupt State Register
spi_host.INTR_ENABLE0x44Interrupt Enable Register
spi_host.INTR_TEST0x84Interrupt Test Register
spi_host.ALERT_TEST0xc4Alert Test Register
spi_host.CONTROL0x104Control register
spi_host.STATUS0x144Status register
spi_host.CONFIGOPTS0x184Configuration options register.
spi_host.CSID0x1c4Chip-Select ID
spi_host.COMMAND0x204Command Register
spi_host.RXDATA0x244SPI Receive Data.
spi_host.TXDATA0x284SPI Transmit Data.
spi_host.ERROR_ENABLE0x2c4Controls which classes of errors raise an interrupt.
spi_host.ERROR_STATUS0x304Indicates that any errors that have occurred.
spi_host.EVENT_ENABLE0x344Controls which classes of SPI events raise an interrupt.

INTR_STATE

Interrupt State Register

  • Offset: 0x0
  • Reset default: 0x0
  • Reset mask: 0x3

Fields

BitsTypeResetNameDescription
31:2Reserved
1rw1c0x0spi_eventEvent-related interrupts, see EVENT_ENABLE register for more information.
0rw1c0x0errorError-related interrupts, see ERROR_ENABLE register for more information.

INTR_ENABLE

Interrupt Enable Register

  • Offset: 0x4
  • Reset default: 0x0
  • Reset mask: 0x3

Fields

BitsTypeResetNameDescription
31:2Reserved
1rw0x0spi_eventEnable interrupt when INTR_STATE.spi_event is set.
0rw0x0errorEnable interrupt when INTR_STATE.error is set.

INTR_TEST

Interrupt Test Register

  • Offset: 0x8
  • Reset default: 0x0
  • Reset mask: 0x3

Fields

BitsTypeResetNameDescription
31:2Reserved
1wo0x0spi_eventWrite 1 to force INTR_STATE.spi_event to 1.
0wo0x0errorWrite 1 to force INTR_STATE.error to 1.

ALERT_TEST

Alert Test Register

  • Offset: 0xc
  • Reset default: 0x0
  • Reset mask: 0x1

Fields

BitsTypeResetNameDescription
31:1Reserved
0wo0x0fatal_faultWrite 1 to trigger one alert event of this kind.

CONTROL

Control register

  • Offset: 0x10
  • Reset default: 0x7f
  • Reset mask: 0xe000ffff

Fields

BitsTypeResetName
31rw0x0SPIEN
30rw0x0SW_RST
29rw0x0OUTPUT_EN
28:16Reserved
15:8rw0x0TX_WATERMARK
7:0rw0x7fRX_WATERMARK

CONTROL . SPIEN

Enables the SPI host. On reset, this field is 0, meaning that no transactions can proceed.

CONTROL . SW_RST

Clears the entire IP to the reset state when set to 1, including the FIFOs, the CDC’s, the core state machine and the shift register. In the current implementation, the CDC FIFOs are drained not reset. Therefore software must confirm that both FIFO’s empty before releasing the IP from reset.

CONTROL . OUTPUT_EN

Enable the SPI host output buffers for the sck, csb, and sd lines. This allows the SPI_HOST IP to connect to the same bus as other SPI controllers without interference.

CONTROL . TX_WATERMARK

If EVENT_ENABLE.TXWM is set, the IP will send an interrupt when the depth of the TX FIFO drops below TX_WATERMARK words (32b each).

CONTROL . RX_WATERMARK

If EVENT_ENABLE.RXWM is set, the IP will send an interrupt when the depth of the RX FIFO reaches RX_WATERMARK words (32b each).

STATUS

Status register

  • Offset: 0x14
  • Reset default: 0x0
  • Reset mask: 0xffdfffff

Fields

BitsTypeResetName
31ro0x0READY
30ro0x0ACTIVE
29ro0x0TXFULL
28ro0x0TXEMPTY
27ro0x0TXSTALL
26ro0x0TXWM
25ro0x0RXFULL
24ro0x0RXEMPTY
23ro0x0RXSTALL
22ro0x0BYTEORDER
21Reserved
20ro0x0RXWM
19:16ro0x0CMDQD
15:8ro0x0RXQD
7:0ro0x0TXQD

STATUS . READY

When high, indicates the SPI host is ready to receive commands. Writing to COMMAND when READY is low is an error, and will trigger an interrupt.

STATUS . ACTIVE

When high, indicates the SPI host is processing a previously issued command.

STATUS . TXFULL

When high, indicates that the transmit data fifo is full. Any further writes to RXDATA will create an error interrupt.

STATUS . TXEMPTY

When high, indicates that the transmit data fifo is empty. Note, one transmit item can be pending in the internal transmit datapath (inside the spi_host_byte_select module). This means the transmit data fifo is empty and TXEMTPY will be high, while there is still one packet that needs to be transmitted.

STATUS . TXSTALL

If high, signifies that an ongoing transaction has stalled due to lack of data in the TX FIFO

STATUS . TXWM

If high, the amount of data in the TX FIFO has fallen below the level of CONTROL.TX_WATERMARK words (32b each).

STATUS . RXFULL

When high, indicates that the receive fifo is full. Any ongoing transactions will stall until firmware reads some data from RXDATA.

STATUS . RXEMPTY

When high, indicates that the receive fifo is empty. Any reads from RX FIFO will cause an error interrupt.

STATUS . RXSTALL

If high, signifies that an ongoing transaction has stalled due to lack of available space in the RX FIFO

STATUS . BYTEORDER

The value of the ByteOrder parameter, provided so that firmware can confirm proper IP configuration.

STATUS . RXWM

If high, the number of 32-bits in the RX FIFO now exceeds the CONTROL.RX_WATERMARK entries (32b each).

STATUS . CMDQD

Command queue depth. Indicates how many unread 32-bit words are currently in the command segment queue.

STATUS . RXQD

Receive queue depth. Indicates how many unread 32-bit words are currently in the RX FIFO. When active, this result may an underestimate due to synchronization delays.

STATUS . TXQD

Transmit queue depth. Indicates how many unsent 32-bit words are currently in the TX FIFO. When active, this result may be an overestimate due to synchronization delays. It may also be an underestimate by 1 because of one pending transmit packet in the internal transmit datapath (inside the spi_host_byte_select module).

CONFIGOPTS

Configuration options register.

Contains options for controlling each peripheral. One register per cs_n line

  • Reset default: 0x0
  • Reset mask: 0xefffffff

Instances

NameOffset
CONFIGOPTS0x18

Fields

BitsTypeResetName
31rw0x0CPOL
30rw0x0CPHA
29rw0x0FULLCYC
28Reserved
27:24rw0x0CSNLEAD
23:20rw0x0CSNTRAIL
19:16rw0x0CSNIDLE
15:0rw0x0CLKDIV

CONFIGOPTS . CPOL

The polarity of the sck clock signal. When CPOL is 0, sck is low when idle, and emits high pulses. When CPOL is 1, sck is high when idle, and emits a series of low pulses.

CONFIGOPTS . CPHA

The phase of the sck clock signal relative to the data. When CPHA = 0, the data changes on the trailing edge of sck and is typically sampled on the leading edge. Conversely if CPHA = 1 high, data lines change on the leading edge of sck and are typically sampled on the trailing edge. CPHA should be chosen to match the phase of the selected device. The sampling behavior is modified by the CONFIGOPTS.FULLCYC bit.

CONFIGOPTS . FULLCYC

Full cycle. Modifies the CPHA sampling behaviour to allow for longer device logic setup times. Rather than sampling the SD bus a half cycle after shifting out data, the data is sampled a full cycle after shifting data out. This means that if CPHA = 0, data is shifted out on the trailing edge, and sampled a full cycle later. If CPHA = 1, data is shifted and sampled with the trailing edge, also separated by a full cycle.

CONFIGOPTS . CSNLEAD

CS_N Leading Time. Indicates the number of half sck cycles, CSNLEAD+1, to leave between the falling edge of cs_n and the first edge of sck. Setting this register to zero corresponds to the minimum delay of one-half sck cycle

CONFIGOPTS . CSNTRAIL

CS_N Trailing Time. Indicates the number of half sck cycles, CSNTRAIL+1, to leave between last edge of sck and the rising edge of cs_n. Setting this register to zero corresponds to the minimum delay of one-half sck cycle.

CONFIGOPTS . CSNIDLE

Minimum idle time between commands. Indicates the minimum number of sck half-cycles to hold cs_n high between commands. Setting this register to zero creates a minimally-wide CS_N-high pulse of one-half sck cycle.

CONFIGOPTS . CLKDIV

Core clock divider. Slows down subsequent SPI transactions by a factor of (CLKDIV+1) relative to the core clock frequency. The period of sck, T(sck) then becomes 2*(CLK_DIV+1)*T(core)

CSID

Chip-Select ID

Controls which device to target with the next command. This register is passed to the core whenever COMMAND is written. The core then asserts cio_csb_o[CSID] during the execution of the command.

  • Offset: 0x1c
  • Reset default: 0x0
  • Reset mask: 0xffffffff

Fields

BitsTypeResetNameDescription
31:0rw0x0CSIDChip Select ID

COMMAND

Command Register

Parameters specific to each command segment. Unlike the CONFIGOPTS multi-register, there is only one command register for controlling all attached SPI devices

  • Offset: 0x20
  • Reset default: 0x0
  • Reset mask: 0x3fff

Fields

BitsTypeResetName
31:14Reserved
13:12wo0x0DIRECTION
11:10wo0x0SPEED
9wo0x0CSAAT
8:0wo0x0LEN

COMMAND . DIRECTION

The direction for the following command: “0” = Dummy cycles (no TX/RX). “1” = Rx only, “2” = Tx only, “3” = Bidirectional Tx/Rx (Standard SPI mode only).

COMMAND . SPEED

The speed for this command segment: “0” = Standard SPI. “1” = Dual SPI. “2”=Quad SPI, “3”: RESERVED.

COMMAND . CSAAT

Chip select active after transaction. If CSAAT = 0, the chip select line is raised immediately at the end of the command segment. If COMMAND.CSAAT = 1, the chip select line is left low at the end of the current transaction segment. This allows the creation longer, more complete SPI transactions, consisting of several separate segments for issuing instructions, pausing for dummy cycles, and transmitting or receiving data from the device.

COMMAND . LEN

Segment Length.

For read or write segments, this field controls the number of 1-byte bursts to transmit and or receive in this command segment. The number of cyles required to send or received a byte will depend on COMMAND.SPEED. For dummy segments, (COMMAND.DIRECTION == 0), this register controls the number of dummy cycles to issue. The number of bytes (or dummy cycles) in the segment will be equal to COMMAND.LEN + 1.

RXDATA

SPI Receive Data.

Reads from this window pull data from the RXFIFO.

The serial order of bit transmission is chosen to match SPI flash devices. Individual bytes are always transmitted with the most significant bit first. Only four-bute reads are supported. If ByteOrder = 0, the first byte received is packed in the MSB of !!RXDATA. For some processor architectures, this could lead to shuffling of flash data as compared to how it is written in memory. In which case, choosing ByteOrder = 1 can reverse the byte-order of each data read, causing the first byte received to be packed into the LSB of !!RXDATA. (Though within each byte the most significant bit is always pulled from the bus first.)

  • Word Aligned Offset Range: 0x24to0x24
  • Size (words): 1
  • Access: ro
  • Byte writes are not supported.

TXDATA

SPI Transmit Data.

Data written to this window is placed into the TXFIFO. Byte-enables are supported for writes.

The serial order of bit transmission is chosen to match SPI flash devices. Individual bytes are always transmitted with the most significant bit first. Multi-byte writes are also supported, and if ByteOrder = 0, the bits of !!TXDATA are transmitted strictly in order of decreasing signficance (i.e. most signicant bit first). For some processor architectures, this could lead to shuffling of flash data as compared to how it is written in memory. In which case, choosing ByteOrder = 1 can reverse the byte-order of multi-byte data writes. (Though within each byte the most significant bit is always sent first.)

  • Word Aligned Offset Range: 0x28to0x28
  • Size (words): 1
  • Access: wo
  • Byte writes are supported.

ERROR_ENABLE

Controls which classes of errors raise an interrupt.

  • Offset: 0x2c
  • Reset default: 0x1f
  • Reset mask: 0x1f

Fields

BitsTypeResetNameDescription
31:5Reserved
4rw0x1CSIDINVALInvalid CSID: If this bit is set, the block sends an error interrupt whenever a command is submitted, but CSID exceeds NumCS.
3rw0x1CMDINVALInvalid Command Errors: If this bit is set, the block sends an error interrupt whenever a command is sent with invalid values for COMMAND.SPEED or COMMAND.DIRECTION.
2rw0x1UNDERFLOWUnderflow Errors: If this bit is set, the block sends an error interrupt whenever there is a read from RXDATA but the RX FIFO is empty.
1rw0x1OVERFLOWOverflow Errors: If this bit is set, the block sends an error interrupt whenever the TX FIFO overflows.
0rw0x1CMDBUSYCommand Error: If this bit is set, the block sends an error interrupt whenever a command is issued while busy (i.e. a 1 is when STATUS.READY is not asserted.)

ERROR_STATUS

Indicates that any errors that have occurred. When an error occurs, the corresponding bit must be cleared here before issuing any further commands.

  • Offset: 0x30
  • Reset default: 0x0
  • Reset mask: 0x3f

Fields

BitsTypeResetNameDescription
31:6Reserved
5rw1c0x0ACCESSINVALIndicates that TLUL attempted to write to TXDATA with no bytes enabled. Such ‘zero byte’ writes are not supported.
4rw1c0x0CSIDINVALIndicates a command was attempted with an invalid value for CSID.
3rw1c0x0CMDINVALIndicates an invalid command segment, meaning either an invalid value of COMMAND.SPEED or a request for bidirectional data transfer at dual or quad speed
2rw1c0x0UNDERFLOWIndicates that firmware has attempted to read from RXDATA when the RX FIFO is empty.
1rw1c0x0OVERFLOWIndicates that firmware has overflowed the TX FIFO
0rw1c0x0CMDBUSYIndicates a write to COMMAND when STATUS.READY = 0.

EVENT_ENABLE

Controls which classes of SPI events raise an interrupt.

  • Offset: 0x34
  • Reset default: 0x0
  • Reset mask: 0x3f

Fields

BitsTypeResetName
31:6Reserved
5rw0x0IDLE
4rw0x0READY
3rw0x0TXWM
2rw0x0RXWM
1rw0x0TXEMPTY
0rw0x0RXFULL

EVENT_ENABLE . IDLE

Assert to send a spi_event interrupt whenever STATUS.ACTIVE goes low

EVENT_ENABLE . READY

Assert to send a spi_event interrupt whenever STATUS.READY goes high

EVENT_ENABLE . TXWM

Assert to send a spi_event interrupt whenever the number of 32-bit words in the TX FIFO is less than CONTROL.TX_WATERMARK. To prevent the reassertion of this interrupt add more data to the TX FIFO, or reduce CONTROL.TX_WATERMARK.

EVENT_ENABLE . RXWM

Assert to send a spi_event interrupt whenever the number of 32-bit words in the RX FIFO is greater than CONTROL.RX_WATERMARK. To prevent the reassertion of this interrupt, read more data from the RX FIFO, or increase CONTROL.RX_WATERMARK.

EVENT_ENABLE . TXEMPTY

Assert to send a spi_event interrupt whenever STATUS.TXEMPTY goes high

EVENT_ENABLE . RXFULL

Assert to send a spi_event interrupt whenever STATUS.RXFULL goes high