Hardware Interfaces and Registers

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
sckoutput

SPI Clock

csboutput

Chip Select# (One hot, active low). The size of this port should match NumCS.

sd[3:0]inout

SPI data bus

Inter-Module Signals: Reference

Inter-Module Signals
Port Name Package::Struct Type Act Width Description
passthrough spi_device_pkg::passthrough req_rsp rsp 1
tl tlul_pkg::tl req_rsp rsp 1

Interrupts:

Interrupt NameTypeDescription
errorEvent

Error-related interrupts, see ERROR_ENABLE register for more information.

spi_eventEvent

Event-related interrupts, see EVENT_ENABLE register for more information.

Security Alerts:

Alert NameDescription
fatal_fault

This fatal alert is triggered when a fatal TL-UL bus integrity fault is detected.

Security Countermeasures:

Countermeasure IDDescription
SPI_HOST.BUS.INTEGRITY

End-to-end bus integrity scheme.

Registers

Summary
Name Offset Length Description
spi_host.INTR_STATE 0x0 4

Interrupt State Register

spi_host.INTR_ENABLE 0x4 4

Interrupt Enable Register

spi_host.INTR_TEST 0x8 4

Interrupt Test Register

spi_host.ALERT_TEST 0xc 4

Alert Test Register

spi_host.CONTROL 0x10 4

Control register

spi_host.STATUS 0x14 4

Status register

spi_host.CONFIGOPTS 0x18 4

Configuration options register.

spi_host.CSID 0x1c 4

Chip-Select ID

spi_host.COMMAND 0x20 4

Command Register

spi_host.RXDATA 0x24 4

SPI Receive Data.

spi_host.TXDATA 0x28 4

SPI Transmit Data.

spi_host.ERROR_ENABLE 0x2c 4

Controls which classes of errors raise an interrupt.

spi_host.ERROR_STATUS 0x30 4

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

spi_host.EVENT_ENABLE 0x34 4

Controls which classes of SPI events raise an interrupt.

spi_host.INTR_STATE @ 0x0

Interrupt State Register

Reset default = 0x0, mask 0x3
31302928272625242322212019181716
 
1514131211109876543210
  spi_event error
BitsTypeResetNameDescription
0rw1c0x0error

Error-related interrupts, see ERROR_ENABLE register for more information.

1rw1c0x0spi_event

Event-related interrupts, see EVENT_ENABLE register for more information.


spi_host.INTR_ENABLE @ 0x4

Interrupt Enable Register

Reset default = 0x0, mask 0x3
31302928272625242322212019181716
 
1514131211109876543210
  spi_event error
BitsTypeResetNameDescription
0rw0x0error

Enable interrupt when INTR_STATE.error is set.

1rw0x0spi_event

Enable interrupt when INTR_STATE.spi_event is set.


spi_host.INTR_TEST @ 0x8

Interrupt Test Register

Reset default = 0x0, mask 0x3
31302928272625242322212019181716
 
1514131211109876543210
  spi_event error
BitsTypeResetNameDescription
0wo0x0error

Write 1 to force INTR_STATE.error to 1.

1wo0x0spi_event

Write 1 to force INTR_STATE.spi_event to 1.


spi_host.ALERT_TEST @ 0xc

Alert Test Register

Reset default = 0x0, mask 0x1
31302928272625242322212019181716
 
1514131211109876543210
  fatal_fault
BitsTypeResetNameDescription
0wo0x0fatal_fault

Write 1 to trigger one alert event of this kind.


spi_host.CONTROL @ 0x10

Control register

Reset default = 0x7f, mask 0xe000ffff
31302928272625242322212019181716
SPIEN SW_RST OUTPUT_EN  
1514131211109876543210
TX_WATERMARK RX_WATERMARK
BitsTypeResetNameDescription
7:0rw0x7fRX_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).

15:8rw0x0TX_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).

28:16Reserved
29rw0x0OUTPUT_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.

30rw0x0SW_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.

31rw0x0SPIEN

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


spi_host.STATUS @ 0x14

Status register

Reset default = 0x0, mask 0xffdfffff
31302928272625242322212019181716
READY ACTIVE TXFULL TXEMPTY TXSTALL TXWM RXFULL RXEMPTY RXSTALL BYTEORDER   RXWM CMDQD
1514131211109876543210
RXQD TXQD
BitsTypeResetNameDescription
7:0ro0x0TXQD

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,

15:8ro0x0RXQD

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.

19:16ro0x0CMDQD

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

20ro0x0RXWM

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

21Reserved
22ro0x0BYTEORDER

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

23ro0x0RXSTALL

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

24ro0x0RXEMPTY

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

25ro0x0RXFULL

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

26ro0x0TXWM

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

27ro0x0TXSTALL

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

28ro0x0TXEMPTY

When high, indicates that the transmit data fifo is empty.

29ro0x0TXFULL

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

30ro0x0ACTIVE

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

31ro0x0READY

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.


spi_host.CONFIGOPTS @ 0x18

Configuration options register.

Reset default = 0x0, mask 0xefffffff

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

31302928272625242322212019181716
CPOL_0 CPHA_0 FULLCYC_0   CSNLEAD_0 CSNTRAIL_0 CSNIDLE_0
1514131211109876543210
CLKDIV_0
BitsTypeResetNameDescription
15:0rw0x0CLKDIV_0

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)

19:16rw0x0CSNIDLE_0

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.

23:20rw0x0CSNTRAIL_0

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.

27:24rw0x0CSNLEAD_0

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

28Reserved
29rw0x0FULLCYC_0

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.

30rw0x0CPHA_0

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.

31rw0x0CPOL_0

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.


spi_host.CSID @ 0x1c

Chip-Select ID

Reset default = 0x0, mask 0xffffffff

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.

31302928272625242322212019181716
CSID...
1514131211109876543210
...CSID
BitsTypeResetNameDescription
31:0rw0x0CSID

Chip Select ID


spi_host.COMMAND @ 0x20

Command Register

Reset default = 0x0, mask 0x3fff

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

31302928272625242322212019181716
 
1514131211109876543210
  DIRECTION SPEED CSAAT LEN
BitsTypeResetNameDescription
8:0wo0x0LEN

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.

9wo0x0CSAAT

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.

11:10wo0x0SPEED

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

13:12wo0x0DIRECTION

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).


spi_host.RXDATA @ + 0x24
1 item ro window
Byte writes are not supported
310
+0x24 

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.)


spi_host.TXDATA @ + 0x28
1 item wo window
Byte writes are supported
310
+0x28 

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.)


spi_host.ERROR_ENABLE @ 0x2c

Controls which classes of errors raise an interrupt.

Reset default = 0x1f, mask 0x1f
31302928272625242322212019181716
 
1514131211109876543210
  CSIDINVAL CMDINVAL UNDERFLOW OVERFLOW CMDBUSY
BitsTypeResetNameDescription
0rw0x1CMDBUSY

Command 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.)

1rw0x1OVERFLOW

Overflow Errors: If this bit is set, the block sends an error interrupt whenever the TX FIFO overflows.

2rw0x1UNDERFLOW

Underflow 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.

3rw0x1CMDINVAL

Invalid 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.

4rw0x1CSIDINVAL

Invalid CSID: If this bit is set, the block sends an error interrupt whenever a command is submitted, but CSID exceeds NumCS.


spi_host.ERROR_STATUS @ 0x30

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

Reset default = 0x0, mask 0x3f
31302928272625242322212019181716
 
1514131211109876543210
  ACCESSINVAL CSIDINVAL CMDINVAL UNDERFLOW OVERFLOW CMDBUSY
BitsTypeResetNameDescription
0rw1c0x0CMDBUSY

Indicates a write to COMMAND when STATUS.READY = 0.

1rw1c0x0OVERFLOW

Indicates that firmware has overflowed the TX FIFO

2rw1c0x0UNDERFLOW

Indicates that firmware has attempted to read from RXDATA when the RX FIFO is empty.

3rw1c0x0CMDINVAL

Indicates an invalid command segment, meaning either an invalid value of COMMAND.SPEED or a request for bidirectional data transfer at dual or quad speed

4rw1c0x0CSIDINVAL

Indicates a command was attempted with an invalid value for CSID.

5rw1c0x0ACCESSINVAL

Indicates that TLUL attempted to write to TXDATA with no bytes enabled. Such 'zero byte' writes are not supported.


spi_host.EVENT_ENABLE @ 0x34

Controls which classes of SPI events raise an interrupt.

Reset default = 0x0, mask 0x3f
31302928272625242322212019181716
 
1514131211109876543210
  IDLE READY TXWM RXWM TXEMPTY RXFULL
BitsTypeResetNameDescription
0rw0x0RXFULL

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

1rw0x0TXEMPTY

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

2rw0x0RXWM

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.

3rw0x0TXWM

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.

4rw0x0READY

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

5rw0x0IDLE

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