Mailbox Client Intel FPGA IP User Guide

Updated for Intel Quartus Prime Design Suite: 21.3, IP Version: 20.1.0. The Mailbox Client Intel FPGA IP core is a bridge between a host and the secure device manager (SDM). You use the Mailbox Client Intel FPGA IP to send commands and receive status from SDM peripheral clients, such as the Voltage Sensor Intel FPGA IP and Chip ID Intel FPGA IP.

mailbox. client, stratix. 10, agilex, RSU, remote system update, client IP peripheral devices, device configuration, driver API, crypto services

Intel Corporation

Mailbox Client Intel FPGA IP User Guide

When set, enables the crypto AXI target interface. (2) This feature is only available for Intel Agilex devices. 1. Mailbox Client Intel FPGA IP User Guide.

File Info : application/pdf, 46 Pages, 429.12KB

ug-20087

Mailbox Client Intel® FPGA IP User Guide
Updated for Intel® Quartus® Prime Design Suite: 21.3 IP Version: 20.1.0

Subscribe Send Feedback

UG-20087 | 2021.11.10 Latest document on the web: PDF | HTML

Contents
Contents
1. Mailbox Client Intel FPGA IP User Guide........................................................................ 3 1.1. Device Family Support............................................................................................4 1.2. Parameters........................................................................................................... 5 1.3. Mailbox Client Intel FPGA Core Interface Signals....................................................... 6 1.3.1. Clock and Reset Interfaces..........................................................................6 1.3.2. Avalon Memory-Mapped Interface................................................................ 7 1.3.3. AXI Target Interface...................................................................................7 1.4. Mailbox Client Intel FPGA IP Avalon MM Memory Map .................................................9 1.4.1. Interrupt Enable Register.......................................................................... 10 1.4.2. Interrupt Status Register ......................................................................... 11 1.4.3. Timer Registers....................................................................................... 12 1.5. Commands and Responses.................................................................................... 14 1.5.1. Operation Commands............................................................................... 14 1.5.2. Error Code Responses...............................................................................22 1.5.3. Error Code Recovery.................................................................................24 1.6. Specifying the Command and Response FIFO Depths................................................ 25 1.7. Enabling Cryptographic Services............................................................................ 25 1.8. Using the Mailbox Client Intel FPGA IP.................................................................... 26 1.9. Mailbox Client Intel FPGA IP Core Use Case Examples............................................... 30 1.10. Nios II HAL Driver.............................................................................................. 32 1.10.1. Driver API............................................................................................. 32 1.11. Mailbox Client Intel FPGA IP User Guide Archives....................................................36 1.12. Document Revision History for the Mailbox Client Intel FPGA IP User Guide................ 37
2. Appendix: CONFIG_STATUS and RSU_STATUS Error Code Descriptions........................ 42

Mailbox Client Intel® FPGA IP User Guide 2

Send Feedback

UG-20087 | 2021.11.10 Send Feedback

1. Mailbox Client Intel FPGA IP User Guide

Figure 1.

The Mailbox Client Intel FPGA IP is a bridge between a host and the secure device manager (SDM). Available for Intel® Stratix® 10 and Intel AgilexTM devices, you use
the Mailbox Client Intel FPGA IP to send commands and receive status from SDM
peripheral clients. The Mailbox Client defines functions that the SDM runs.

The following pre-defined functions are available: · Reading the Chip ID · Reading temperature sensors · Reading voltage sensors · Reading and writing external quad serial peripheral interface (SPI) flash memory · Performing remote system updates (RSU) · Enabling cryptographic services(1)

The following block diagram shows how to use the Mailbox Client Intel FPGA IP in an interactive session. The diagram also emphasizes different ways of communicating with IP through the Host Controller.

Mailbox Client Intel FPGA IP System Block Diagram

PC Running System Console Host System

Intel FPGA IP Soft IP Host Controller

Mailbox Client Intel FPGA IP

JTAG to

Avalon Master

Avalon MM Interface

FIFO

Nios II

Processor

IRQ

FIFO

Controller

Ethernet IP Custom Logic PCIe Hard IP

SDM Communication
Hub

Mailbox Driver

Hard IP
Secure Device Manager

This block diagram includes the following components:

(1) This feature is available for Intel Agilex devices in Intel Quartus® Prime software version 21.3 or later.

Intel Corporation. All rights reserved. Intel, the Intel logo, and other Intel marks are trademarks of Intel Corporation or its subsidiaries. Intel warrants performance of its FPGA and semiconductor products to current specifications in accordance with Intel's standard warranty, but reserves the right to make changes to any products and services at any time without notice. Intel assumes no responsibility or liability arising out of the application or use of any information, product, or service described herein except as expressly agreed to in writing by Intel. Intel customers are advised to obtain the latest version of device specifications before relying on any published information and before placing orders for products or services. *Other names and brands may be claimed as the property of others.

ISO 9001:2015 Registered

1. Mailbox Client Intel FPGA IP User Guide UG-20087 | 2021.11.10
· Host Controller: provides possible ways of accessing the Mailbox Client Intel FPGA IP. Use any of the specified ways to communicate with the host controller: -- System Console with the JTAG to Avalon® Master Bridge Intel FPGA IP. The System Console provides a Tcl Console pane that you can use to run the IP functions. The JTAG to Avalon Master Bridge Intel FPGA IP translates the commands it receives from the System Console to Avalon Memory-Mapped (Avalon MM) format that the Mailbox Client Intel FPGA IP requires. -- Nios® II processor: sends commands to the Mailbox Client Intel FPGA IP.
-- Custom logic: It sends commands to the Mailbox Client Intel FPGA IP.
-- PCIe* Hard IP
-- Ethernet IP
· Mailbox Client Intel FPGA IP: drives commands and receives responses from the SDM. This component includes FIFOs with a maximum depth of 1024 entries to store commands and responses. The Mailbox Client Intel FPGA IP interrupt indicates when the input FIFO in full and when the output FIFO contains valid data. You can size these FIFOs to accommodate the commands the you intend to send.
Intel provides a reference design that uses the System Console and the JTAG master to drive the Mailbox Client Intel FPGA IP. In the Intel Design Store, search for Intel Agilex Mailbox Client Intel FPGA IP Core Design Example (QSPI flash Access and Remote System Update) to view the design.
Related Information
· Avalon Interface Specifications
· Secure Device Manager in Intel Stratix 10 Devices
· Operation Commands on page 14
· Analyzing and Debugging Designs with System Console
· Agilex Mailbox Client Intel FPGA IP Core Design Example (QSPI flash Access and Remote System Update)
1.1. Device Family Support
The following lists the device support level definitions for Intel FPGA IPs:
· Advance support -- The IP is available for simulation and compilation for this device family. Timing models include initial engineering estimates of delays based on early post-layout information. The timing models are subject to change as silicon testing improves the correlation between the actual silicon and the timing models. You can use this IP for system architecture and resource utilization studies, simulation, pinout, system latency assessments, basic timing assessments (pipeline budgeting), and I/O transfer strategy (data-path width, burst depth, I/O standards tradeoffs).
· Preliminary support -- The IP is verified with preliminary timing models for this device family. The IP meets all functional requirements, but might still be undergoing timing analysis for the device family. It can be used in production designs with caution.
· Final support -- The IP is verified with final timing models for this device family. The IP meets all functional and timing requirements for the device family and can be used in production designs.

Mailbox Client Intel® FPGA IP User Guide 4

Send Feedback

1. Mailbox Client Intel FPGA IP User Guide UG-20087 | 2021.11.10

Table 1.

Device Family Support
Device Family Intel Stratix 10
Intel Agilex

Support Final Final

Related Information · Mailbox Client Intel FPGA IP Release Notes · Mailbox Client with Avalon Streaming Interface Intel FPGA IP Release Notes

1.2. Parameters

Parameter Name Mailbox Client Parameters Command FIFO Depth Response FIFO Depth Crypto Memory Timeout Value
Memory Target Parameters HAS_OFFLOAD(2)

Value
1 - 1024 1 - 1024 0x00002710
0x7FFFFFFFF
0, 1

Description
Depth of the command FIFO Depth of the response FIFO The timeout for the cryptographic service. Specify value within the minimum and maximum timeout value. · 0x7FFFFFFF: Maximum memory timeout value · 0x002710: Minimum memory timeout value
Enables the cryptographic offloading feature. When set, enables the crypto AXI target interface.

(2) This feature is only available for Intel Agilex devices.
Send Feedback

Mailbox Client Intel® FPGA IP User Guide 5

1. Mailbox Client Intel FPGA IP User Guide UG-20087 | 2021.11.10

1.3. Mailbox Client Intel FPGA Core Interface Signals

The host communicates with the Mailbox Client Intel FPGA over its Avalon MemoryMapped (Avalon MM) interface. For Intel Agilex devices, the AXI target interface is available if you enabled HAS_OFFLOAD parameter. Through the AXI interface, the crypto service has access to the lowest 1GB of memory, with a maximum data size of 512 MB per each read and write operation.

The following figure illustrates the Mailbox Client Intel FPGA IP interfaces.

Figure 2.

Mailbox Client Intel FPGA IP Interfaces

The AXI target interface is only available in the Intel Agilex devices with enabled HAS_OFFLOAD parameter.

Mailbox Client Intel FPGA IP

in_clk_clk

clk

in_reset_reset

reset

irq

irq_irq

Avalon Memory-Mapped
Interface

avmm_address[3..0]
avmm_write avmm_writedata[31..0] avmm_read avmm_readdata[31..0]
avmm_readdatavalid

address
write writedata read readdata
readdatavalid

awid awaddr awlen
... awsize
rid

axi_target_awid[3..0] axi_target_awaddr[31..0]
axi_target_awlen[7..0]
axi_target_awsize[2..0]
...
axi_target_rid[3..0]

AXI Target Interface

Note:

For information about the AXI target interface, refer to Table 4 on page 7.
Related Information · Intel Stratix 10 Configuration User Guide
For information about including the Reset Release IP in your design. · Intel Agilex Configuration User Guide
For information about including the Reset Release IP in your design.

1.3.1. Clock and Reset Interfaces

Table 2.

Clock and Reset Interfaces

Signal Role clk

Width 1

Direction Input

reset

Input

Description
Input clock to clock the IP. The maximum frequency is 250 MHz.
Reset that resets the IP. To reset the IP, assert the reset signal high for at least 2 clk cycles. To ensure the Mailbox Client Intel FPGA IP functions correctly when the device enters user mode, your design must include the Reset Release Intel FPGA IP to hold the reset until the FPGA fabric entered user mode. Intel recommends using a reset synchronizer when connecting the user reset or output of the Reset Release IP to the reset
continued...

Mailbox Client Intel® FPGA IP User Guide 6

Send Feedback

1. Mailbox Client Intel FPGA IP User Guide UG-20087 | 2021.11.10

Signal Role irq

Width 1

Direction Output

Description
port of the Mailbox Client IP. To implement the reset synchronizer, use the Reset Bridge Intel FPGA IP available in the Platform Designer.
Note: For IP instantiation and connection guidelines in the Platform Designer, refer to the Required Communication and Host Components for the Remote System Update Design Example figure in the Intel Stratix 10 Configuration User Guide.
Note: For IP instantiation guidelines, refer to the Configuration User Guide.
Interrupt signal. Drives the value of the AND of the interrupt status and interrupt enable registers.

1.3.2. Avalon Memory-Mapped Interface

The Avalon MM interface is standard memory-mapped interface. For detailed definitions of these signals, refer to the Avalon Memory-Mapped Interfaces chapter in the Avalon Interface Specifications.

Table 3.

Avalon Memory-Mapped Interface

Signal Role

Width

Direction

avmm_address

Input

avmm_write

Input

avmm_read

Input

avmm_writedata

Input

avmm_readdata

Output

avmm_readdatavalid

Output

Description Avalon MM address. Avalon MM write request. Avalon MM read request. Avalon MM write data bus. Avalon MM read data bus. Avalon MM read data valid.

Related Information · Avalon Interface Specifications · Avalon Memory-Mapped Interface Signal Roles

1.3.3. AXI Target Interface

The AXI target interface is standard advanced extensible interface (AXI). This interface is accessible when you enabled the crypto services features. The crypto services features are available for the Intel Agilex devices.

Table 4.

AXI Target Interface
The table displays command, response, and urgent interface signals.

Signal Role

Width

Direction

Description

AXI Target Clock and Reset Signals

axi_in_clk

Input

AXI* interface clock.

axi_in_reset

Input

AXI interface reset.

AXI Target Write Address Channel Signals

continued...

Send Feedback

Mailbox Client Intel® FPGA IP User Guide 7

1. Mailbox Client Intel FPGA IP User Guide UG-20087 | 2021.11.10

Signal Role axi_target_awid axi_target_awaddr axi_target_awlen axi_target_awsize axi_target_awburst axi_target_awlock axi_target_awcache axi_target_awprot axi_target_awqos axi_target_awvalid

Width 4 32 8 3 2 1 4 3 4 1

axi_target_awuser

axi_target_awready

AXI Target Write Data Channel Signals

axi_target_wdata

axi_target_wlast

axi_target_wready

axi_target_wvalid

axi_target_wstrb

AXI Target Write Response Channel Signals

axi_target_bid

axi_target_bresp

axi_target_bvalid

axi_target_bready

AXI Target Read Data Channel Signals

Direction Output Output Output Output Output Output Output Output Output Output
Output Input

Description
AXI identification tag for write transaction.
AXI address of the first transfer in a write transaction.
AXI length. Identifies the exact number of data transfers in a write transaction.
AXI size. Identifies the number of bytes in each data transfer in a write transaction.
AXI burst type. Indicates how address changes between each transfer in a write transaction.
Provides information about the atomic characteristics of a AXI write transaction.
Indicates how a write transaction is required to progress through a system.
Protection attributes of a write transaction: privilege, security level, and access type.
Quality of Service identifier for a write transaction
AXI valid signal for a write transaction. Indicates that the write address channel signals are valid.
User-defined extension for the write address channel.
AXI ready signal for write address. Indicates that a transfer on the write address channel can be accepted.

Output Output
Input Output Output

AXI write data.
AXI write transaction last data transfer. Indicates whether the current transfer is the last data transfer in a write transaction.
AXI ready signal for write data. Indicates that a write data channel transfer can be accepted.
AXI valid signal for write data. Indicates that a write data channel signals are valid.
AXI write strobes. Indicates the byte lane holding valid data.

Input Input Input Output

AXI identification tag for write response.
AXI write response. Indicates write response status.
AXI valid signal for write response. Indicates that the write response channel signals are valid.
AXI ready signal for write response. Indicates that the write response channel transfer can be accepted.
continued...

Mailbox Client Intel® FPGA IP User Guide 8

Send Feedback

1. Mailbox Client Intel FPGA IP User Guide UG-20087 | 2021.11.10

Signal Role axi_target_rdata axi_target_rresp axi_target_rlast

Width 64 2 1

axi_target_rready

axi_target_rvalid

axi_target_rid

AXI Target Read Response Channel Signals

axi_target_arid

axi_target_araddr

axi_target_arlen

axi_target_arsize

axi_target_arburst

axi_target_arlock

axi_target_arcache

axi_target_arprot

axi_target_arqos

axi_target_arvalid

axi_target_aruser

axi_target_arready

Direction Input Input Input
Output
Input Input

Description
AXI read data.
AXI read response. Indicates read transfer status.
AXI read transaction last data transfer. Indicates whether the current transfer is the last data transfer in a read transaction.
AXI read data channel ready signal. Indicates that a transfer on the read data channel can be accepted.
AXI valid signal for read data channel. Indicates that the read data channel signals are valid.
AXI identification tag for read data and response.

Output Output Output Output
Output Output Output Output Output Output Output Input

AXI identification tag for read address transaction.
AXI address of the first transfer in a read transaction.
AXI length. Identifies the number of data transfers during the read transaction.
AXI size. Identifies the number of bytes in each data transfer in a read transaction.
AXI burst type. Indicates how address changes between each transfer in a read transaction.
Provides information about the atomic characteristics of a AXI read transaction.
Indicates how a read transaction is required to progress through a system.
Protection attributes of a read transaction: privilege, security level, and access type.
Quality of Service identifier for a read transaction.
AXI valid signal for read transaction. Indicates that the read address channel signals are valid.
AXI user-defined extension for the read address channel.
AXI read address channel ready signal. Indicates that a transfer on the read address channel can be accepted.

1.4. Mailbox Client Intel FPGA IP Avalon MM Memory Map

Table 5.

Avalon MM Memory Map

Offset (word)

R/W

Base address + 0

Base address + 1

30:2

Command

Command last word (eop)

0 continued...

Send Feedback

Mailbox Client Intel® FPGA IP User Guide 9

1. Mailbox Client Intel FPGA IP User Guide UG-20087 | 2021.11.10

Offset (word)

R/W

30:2

Base address + 2

Command FIFO empty space

Base address + 3 N/A

Reserved

Base address + 4 N/A

Reserved

Base address + 5

Response data

Base address + 6

Response FIFO fill level

EOP

SOP

Base address + 7 R/W

Interrupt enable register (IER)

Base address + 8

Interrupt status register (ISR)

Base address + 9 R/W

Timer 1 enable

Timer 1 period

Base address + 10 R/W

Timer 2 enable

Timer 2 period

1.4.1. Interrupt Enable Register

Use the Interrupt Enable register to enable or disable interrupts.

Table 6.

Interrupt Enable Register

Note:

These enable bits do not prevent the value of interrupt status bit from showing up in ISR, they only prevent the interrupt status bit from causing interrupt output assertion.

Bit 31:8
7
6
5
4

Fields
Reserved EN_CRYPTO_ERROR_ RECOVERY_PROGRESS(3)

Access R/W

EN_CRYPTO_ MEMORY_TIMEOUT(3)

R/W

EN_BACKPRESSURE_TIMEOUT

R/W

EN_EOP_TIMEOUT

R/W

Default Value

Description

0x0

The enable interrupt bit for crypto service error

recovery progress status.

· 1: Enable the crypto service error recovery progress interrupt

· 0: Disable the crypto service error recovery progress interrupt

0x0

The enable interrupt bit for the crypto service

client-side memory timeout.

· 1: Enable the crypto service client-side memory timeout interrupt

· 0: Disable the crypto service client-side memory timeout interrupt

0x0

The enable interrupt bit for SDM backpressure

timeout.

· 1: Enable the SDM backpressure timeout interrupt

· 0: Disable the SDM backpressure timeout interrupt

0x0

The enable interrupt bit for EN_EOP_TIMEOUT.

· 1: Enable the EOP timeout interrupt

· 0: disable the EOP timeout interrupt

continued...

(3) The crypto service feature is only available for Intel Agilex devices.

Mailbox Client Intel® FPGA IP User Guide 10

Send Feedback

1. Mailbox Client Intel FPGA IP User Guide UG-20087 | 2021.11.10

Bit

Fields

EN_COMMAND_INVALID

Reserved

EN_CMD_FIFO_NOT_FULL

EN_DATA_VALID

Access R/W
-- R/W
R/W

Default Value
0x0
-- 0x0
0x0

Description
The enable interrupt bit for COMMAND_INVALID. · 1: Enable the command invalid interrupt · 0: Disable the command invalid interrupt
Reserved.
The enable for the command FIFO full interrupt. · 1: Enable the FIFO full interrupt · 0: Disable the FIFO full interrupt
The enable for the data valid interrupt. · 1: Enable the data valid interrupt · 0: Disable the data valid interrupt

1.4.2. Interrupt Status Register

Use the interrupt_status register to monitor the status of the FIFO and identify invalid commands.

Your logic can poll the error bits of the interrupt_status register. Or, you can configure the EN_COMMAND_INVALID bit of the interrupt enable register to interrupt when an error occurs.

When an error occurs, the Mailbox Client IP clears all pending responses. Your logic should not expect any response from Mailbox Client IP after an error occurs. Your logic must assert reset for a minimum of 10 clock cycles to reset the Mailbox Client IP.

Table 7.
Bit 31:8
7
6
5

Interrupt Status Register

Fields

Access

Reserved

CRYPTO_ERROR_RECOVERY_

PROGRESS(4)

CRYPTO_MEMORY_TIMEOUT(4)

BACKPRESSURE_TIMEOUT

Default Value

Description

0x0

Error recovery flow progress interrupt for the

cryptographic (crypto) flow.

· 1: Indicates that the crypto error recovery is in progress. You may use this bit to report the progress of the soft IP error recovery. While in recovery, the SDM is unable to perform read/ write operations from the memory.

· 0: Indicates the crypto error recovery is completed.

0x0

Cryptographic services timer for memory target

interrupt. Timeout value is set by Crypto

Memory Timeout Value parameter in the

Mailbox Client IP.

· 1: Indicates that the timeout occurred in either the memory target write or read path in the AXI transaction. You must reset the Mailbox

Client IP (in_reset and axi_in_reset) and your memory target device.

· 0: No timeout occurred

0x0

SDM backpressure timer interrupt.

continued...

(4) The crypto service feature is only available for Intel Agilex devices.

Send Feedback

Mailbox Client Intel® FPGA IP User Guide 11

1. Mailbox Client Intel FPGA IP User Guide UG-20087 | 2021.11.10

Bit

Fields

EOP_TIMEOUT

COMMAND_INVALID

Reserved

CMD_FIFO_NOT_FULL

DATA_VALID

Access
R
R -- R R

Default Value
0x0
0x0
-- 0x0 0x0

Description
· 1: The SDM backpressure timer has timeout. Indicates that a fatal error occurred in SDM. You must reset the device. To reset, reconfigure or power cycle the device.
· 0: The SDM backpressure timer has not timeout.
End of Packet (EOP) timer interrupt. · 1: Indicates that the EOP timer has timeout.
You must reset the Mailbox Client IP. · 0: The EOP timer has not timeout. Indicates that the Mailbox Client IP did not receive the full command with EOP due to: · Mailbox did not receive the last argument with
EOP. · Mailbox already received all arguments without
the EOP in it.
Invalid command interrupt. Indicates a mismatch between the command length specified in the command header and the number of words sent. Hardware clears this bit. · 1: Indicates that the command is invalid. You
must reset the Mailbox client. · 0: The command is valid.
Reserved.
Command FIFO is not full interrupt. · 1: Indicates command FIFO is not full. The
client can drive data. · 0: Indicates the FIFO is full. The FIFO automatically clears this bit. You do not need to clear this bit manually.
Data valid interrupt. · 1: Indicates that valid data is available. The
master can read. · 0: Indicates the FIFO is empty. The FIFO automatically clears this bit. You do not need to clear this bit manually.

1.4.3. Timer Registers
Use timer registers to monitor and address incomplete transactions between host and the Mailbox Client IP.

Incomplete Command Transaction Error
When a host fails to send the last command word to the Mailbox Client IP or the system stops sending data before the last word, the incomplete command transaction error occurs. Timer 1 allows you to set a specific transaction time period to complete each command. When the timer's timeout occurs, ISR[4] is set to indicate the error. To recover the system, you must reset the Mailbox Client IP.

Mailbox Client Intel® FPGA IP User Guide 12

Send Feedback

1. Mailbox Client Intel FPGA IP User Guide UG-20087 | 2021.11.10

Table 8.
Bit 31 30:0
Table 9.
Bit 31 30:0

Timer 1 Register
Fields Timer 1 enable
Timer 1 period

Access R/W
R/W

Default Value(5)
0x0
0x7FF_FFFF

Description
Timer 1 period enable bit. The bit is enabled once. · 1: Enable timer 1 · 0: Disable timer 1 If a time out occurs, the timer 1 register becomes disabled. You must apply the Mailbox Client Intel FPGA IP reset. To start the timer 1, you must re-enable it again.
When enabled, the timer counts down the specified period as the maximum number of clock cycles the system has not received a valid command. The timer 1 starts the count down as soon as the transaction writes the first data word into the Command FIFO (base address +0). The timer resets when the Mailbox Client Intel FPGA IP receives complete command transaction, indicated by successfully writing the last word into the command last word register (base address +1). When the timer 1 resets itself, it returns to its default or other defined value.

SDM Backpressure Error

SDM typically backpressures while it processes commands and sends responses. The SDM backpressure error occurs when SDM backpressures for some time period not allowing you to write any data into the Mailbox fabric and SDM. The timer 2, by setting a specific wait time, allows you detect the long wait and take steps to recover your system. When a timer's timeout occurs, ISR[5] is set to indicate an error. Note that this is a fatal error received from SDM, possibly indicating a system error. Resetting the Mailbox Client won't recover the system.

Timer 2 Register
Fields Timer 2 enable
Timer 2 period

Access R/W
R/W

Default Value(6)
0x0
0x7FF_FFFF

Description
Timer 2 period enable bit. The bits is enabled once. · 1: Enable timer 2 · 0: Disable timer 2 If a time out occurs, the timer 2 register becomes disabled. You must apply the Mailbox Client Intel FPGA IP reset. To start the timer 2, you must re-enable it again.
When enabled, the timer counts down the specified period as the maximum number of clock cycles the system has not asserted ready high signal. The SDM backpressures commands sent by host to the Mailbox Client Intel FPGA IP.

(5) Resetting the Mailbox Client IP resets the timer 1 register to the default value. (6) Resetting the Mailbox Client IP resets the timer 2 register to the default value.

Send Feedback

Mailbox Client Intel® FPGA IP User Guide 13

1. Mailbox Client Intel FPGA IP User Guide UG-20087 | 2021.11.10

1.5. Commands and Responses

The host controller communicates with the SDM using command and response packets via the Mailbox Client Intel FPGA IP.

The first word of the command and response packets is a header that provides basic information about the command or response.

Figure 3.

Command and Response Header Format

31 30 29 28 27 26 25 24 23 22 21 20 19 18 17 16 15 14 13 12 11 10 9 8 7 6 5 4 3 2 1 0

Reserved

Length

Command/Error Code

Note:

The LENGTH field in the command header must match the command length of corresponding command.

The following table describes the fields of the header command.

Table 10. Command and Response Header Description

Header Reserved ID
0

Bit [31:28] [27:24]
[23]

Description
Reserved.
The command ID. The response header returns the ID specified in the command header. Refer to Operation Commands for command descriptions.
Reserved.

LENGTH
Reserved Command Code/Error Code

[22:12]
[11] [10:0]

Number of words of arguments following the header. The IP responds with an error if a wrong number of words of arguments is entered for a given command.
Reserved. Must be set to 0.
Command Code specifies the command. The Error Code indicates whether the command succeeded or failed. In the command header, these bits represent command code. In the response header, these bits represent error code. If the command succeeds, the Error Code is 0. If the command fails, refer to the error codes defined in the Error Code Responses.

1.5.1. Operation Commands

Resetting Quad SPI Flash

Important:

For Intel Stratix 10 devices, do not reset the quad SPI flash when used as the configuration device and data storage device with FPGA. Resetting the quad SPI flash during the FPGA configuration and reconfiguration, or in the QSPI's READ/WRITE/ ERASE operations, causes undefined behavior for quad SPI flash and the FPGA. To recover from the unresponsive behavior, you must power cycle your device. To reset the quad SPI flash via the external host, you must first complete the FPGA configuration and reconfiguration, or a quad SPI operation, and only then toggle the reset. The quad SPI operation is complete when the exclusive access to the quad SPI flash is closed by issuing the QSPI_CLOSE command via the Mailbox Client Intel FPGA
IP or CLOSE command via the Serial Flash Mailbox Client Intel FPGA IP.

Mailbox Client Intel® FPGA IP User Guide 14

Send Feedback

1. Mailbox Client Intel FPGA IP User Guide UG-20087 | 2021.11.10

Important:

For Intel Agilex devices, you must connect the serial flash or quad SPI flash reset pin to the AS_nRST pin. The SDM must fully control the QSPI reset. Do not connect the quad SPI reset pin to any external host.

Table 11. Command List and Description

Command NOOP

Code Command Response (Hex) Length (7) Length (7)

Description

Sends an OK status response.

GET_IDCODE

GET_CHIPID

GET_USERCODE 13

GET_VOLTAGE

GET_

TEMPERATURE

1 2 1 1
n(10)

The response contains one argument which is the JTAG IDCODE for the device
The response contains 64-bit CHIPID value with the least significant word first.
The response contains one argument which is the 32-bit JTAG USERCODE that the configuration bitstream writes to the device.
The GET_VOLTAGE command has a single argument which is a bitmask specifying the channels to read. Bit 0 specifies channel 0, bit 1 specifies channel 1, and so on. The response includes a one-word argument for each bit set in the bitmask. The voltage returned is an unsigned fixed-point number with 16 bits below the binary point. For example, a voltage of 0.75V returns 0x0000C000.(8) (9)
The GET_TEMPERATURE command returns the temperature or temperatures of the core fabric or transceiver channel locations you specify. For Intel Stratix 10 devices, use the sensor_req argument to specify the locations. The sensor_req includes the following fields: · Bits[31:9]: Reserved. · Bits[8:0]: Sensor mask. Specifies the TSD location. The channels return the temperatures for the following locations: · Channel 0: Samples the temperature from the core fabric. · Channels 1- 6: Samples the temperature from the specified
transceiver tile. · Channels 7-8: Samples the temperature from the high-bandwidth
DRAM memory (HBM2) stacks. For Intel Agilex devices, use the sensor_req argument to specify the locations. The sensor_req includes the following fields: · Bits[31:28]: Reserved. · Bits[27:16]: Sensor Location. Specifies the TSD location. · Bits[15:0]: Sensor mask. Specifies the sensors to read for the
sensor location specified. The response contains one word for each temperature requested. If omitted, the command reads channel 0. The least significant bit (lsb) corresponds to sensor 0. The most significant bit (msb) corresponds to channel 15.
continued...

(7) This number does not include the command or response header.
(8) Refer to Intel Stratix 10 Analog to Digital Converter User Guide for more information about reading voltage sensors on Intel Stratix 10 devices.
(9) Refer to Intel Agilex Power Management User Guide for more information about temperature sensor channels and locations.
(10) Index n depends on the number of sensor masks.

Send Feedback

Mailbox Client Intel® FPGA IP User Guide 15

1. Mailbox Client Intel FPGA IP User Guide UG-20087 | 2021.11.10

Command
RSU_IMAGE_ UPDATE
RSU_GET_SPT
CONFIG_ STATUS

Code Command Response (Hex) Length (7) Length (7)

Description

The temperature returned is a signed fixed value with 8 bits below the binary point. For example, a temperature of 10°C returns 0x00000A00. A of temperature -1.5°C returns 0xFFFFFE80.
If the bitmask specifies an invalid Location, the command returns an error code which is any value in the range 0x80000000 -0x800000FF.
For Intel Stratix 10 devices, refer to the Temperature Sensor Channels and Locations in the Intel Stratix 10 Analog to Digital Converter User Guide for more information about sensor locations.
For Intel Agilex devices, refer to the Intel Agilex Power Management User Guide for more information about local build-in temperature sensors.

Triggers reconfiguration from the data source that can be either the

factory or an application image.

This command takes an optional 64-bit argument that specifies the reconfiguration data address in the flash. When sending the argument to the IP, you first send bits [31:0] followed by bits [63:32]. If you do not provide this argument its value is assumed to be 0.

· Bit [31:0]: The start address of an application image.

· Bit [63:32]: Reserved (write as 0).

Once the device processes this command, it returns the response header to response FIFO before it proceeds to reconfigure the device. Ensure the host PC or host controller stops servicing other interrupts and focuses on reading the response header data to indicate the command completed successfully. Otherwise, the host PC or host controller may not be able to receive the response once the reconfiguration process started.

Once the device proceeds with reconfiguration, the link between the external host and FPGA is lost. If you use PCIe in your design, you need to re-enumerate the PCIe link.

Important: When resetting quad SPI, you must follow instructions specified in Resetting Quad SPI Flash on page 14.

RSU_GET_SPT retrieves the quad SPI flash location for the two sub-

partition tables that the RSU uses: SPT0 and SPT1.

The 4-word response contains the following information:

Word

Name

Description

SPT0[63:32]

SPT0 address in quad SPI flash.

SPT0[31:0]

SPT1[63:32]

SPT1 address in quad SPI flash.

SPT1[31:0]

Reports the status of the last reconfiguration. You can use this

command to check the configuration status during and after

configuration. The response contains the following information:

Word

Summary

Description

State

Describes the most recent configuration related error. Returns 0 when there are no configuration errors. The error field has 2 fields: · Upper 16 bits: Major error code. · Lower 16 bits: Minor error code.
continued...

(7) This number does not include the command or response header.

Mailbox Client Intel® FPGA IP User Guide 16

Send Feedback

1. Mailbox Client Intel FPGA IP User Guide UG-20087 | 2021.11.10

Command

Code Command Response (Hex) Length (7) Length (7)

Description

Refer to Appendix: CONFIG_STATUS and RSU_STATUS Error Code Descriptions in the Mailbox Client Intel FPGA IP User Guide for more information.

Quartus

Version

For Intel Stratix 10 devices: Available in Intel Quartus Prime software version 19.4 or later, the field displays:
· Bit [31:28]: Index of the firmware or decision firmware copy that was used the most recently. Possible values are 0, 1, 2, and 3.
· Bit [27:24]: Reserved
· Bit [23:0]: 24'd0
For Intel Agilex devices: Available in Intel Quartus Prime software versions between 19.4 and 21.2, the field displays:
· Bit [31:28]: Index of the firmware or decision firmware copy that was used the most recently. Possible values are 0, 1, 2, and 3.
· Bit [27:24]: Reserved
· Bit [23:16]: Major Quartus release number
· Bit [15:8]: Minor Quartus release number
· Bit [7:0]: Quartus update number
Available in Intel Quartus Prime software version 21.3 or later, the Quartus version displays:
· Bit [31:28]: Index of the firmware or decision firmware copy that was used the most recently. Possible values are 0, 1, 2, and 3.
· Bit [27:24]: Reserved
· Bit [23:16]: Major Quartus release number
· Bit [15:8]: Minor Quartus release number
· Bit [7:0]: Quartus update number
For example, in Intel Quartus Prime software version 21.3.1, the following values represent the major and minor Quartus release numbers, and the Quartus update number:
· Bit [23:16] = 8'd21 = 8'h15
· Bit [15:8] = 8'd3 = 8'h3
· Bit [7:0] = 8'd1 = 8'h1

Pin status

· Bit [31]: Current nSTATUS output value (active low)
· Bit [30]: Detected nCONFIG input value (active low)
· Bit [29:3]: Reserved · Bit [2:0]: The MSEL value at power
up
continued...

(7) This number does not include the command or response header.

Send Feedback

Mailbox Client Intel® FPGA IP User Guide 17

1. Mailbox Client Intel FPGA IP User Guide UG-20087 | 2021.11.10

Command RSU_STATUS

Code Command Response (Hex) Length (7) Length (7)

Description

Soft function Contains the value of each of the soft

status

functions, even if you have not assigned

the function to an SDM pin.

· Bit [31:6]: Reserved

· Bit [5]: HPS_WARMRESET

· Bit [4]: HPS_COLDRESET

· Bit [3]: SEU_ERROR

· Bit [2]: CVP_DONE

· Bit [1]: INIT_DONE

· Bit [0]: CONF_DONE

Error location Contains the error location. Returns 0 if

there are no errors.

Error details Contains the error details. Returns 0 if

there are no errors.

Reports the current remote system upgrade status. You can use this

command to check the configuration status during configuration and

after it has completed. This command returns the following

responses:

Word

Summary

Description

0-1

Current image Flash offset of the currently running

application image.

2-3

Failing image Flash offset of the highest priority failing

application image. If multiple images

are available in flash memory, stores

the value of the first image that failed.

A value of all 0s indicates no failing

images. If there are no failing images,

the remainder of the remaining words of

the status information do not store valid

information.

Note: A rising edge on nCONFIG to reconfigure from ASx4, does not clear this field. Information about failing image only updates when the Mailbox Client receives a new RSU_IMAGE_UPDATE command and successfully configures from the update image.

State

Failure code of the failing image.
The error field has two parts:
· Bit [31:16]: Major error code
· Bit [15:0]: Minor error code
Returns 0 for no failures. Refer to Appendix: CONFIG_STATUS and RSU_STATUS Error Code Descriptions in the Mailbox Client Intel FPGA IP User Guide for more information.

Version

RSU interface version and error source. continued...

(7) This number does not include the command or response header.
Mailbox Client Intel® FPGA IP User Guide 18

Send Feedback

1. Mailbox Client Intel FPGA IP User Guide UG-20087 | 2021.11.10

Command
RSU_NOTIFY QSPI_OPEN QSPI_CLOSE QSPI_SET_CS

Code Command Response (Hex) Length (7) Length (7)

Description

For more information, refer to RSU Status and Error Codes section in the Hard Processor System Remote System Update User Guide.

Error location Stores the error location of the failing

image. Returns 0 for no errors.

Error details Stores the error details for the failing

image. Returns 0 if there are no errors.

Current image Count of the number of retries that

retry counter have been attempted for the current

image. The counter is 0 initially. The

counter is set to 1 after the first retry,

then 2 after a second retry.

Specify the maximum number of retries in your Intel Quartus Prime Settings File (.qsf). The command is:

set_global_assignment -name

RSU_MAX_RETRY_COUNT 3. Valid

values for the MAX_RETRY counter are 1-3. The actual number of available retries is MAX_RETRY -1

This field was added in version 19.3 of the Intel Quartus Prime Pro Edition software.

Clears all error information in the RSU_STATUS response and resets

the retry counter. The one-word argument has the following fields:

· 0x00050000: Clear current reset retry counter. Resetting the current retry counter sets the counter back to zero, as if the current image was successfully loaded for the first time.

· 0x00060000: Clear error status information.

· All other values are reserved.

This command is not available before version 19.3 of the Intel Quartus Prime Pro Edition software.

Requests exclusive access to the quad SPI. You issue this request

before any other QSPI requests. The SDM accepts the request if the

quad SPI is not in use and the SDM is not configuring the device.

Returns OK if the SDM grants access.

The SDM grants exclusive access to the client using this mailbox. Other clients cannot access the quad SPI until the active client relinquishes access using the QSPI_CLOSE command.

Access to the quad SPI flash memory devices via any mailbox client IP is not available by default in designs that include the HPS, unless you disable the QSPI in HPS software configuration.

Important: When resetting quad SPI, you must follow instructions specified in Resetting Quad SPI Flash on page 14.

Closes the exclusive access to the quad SPI interface.

Important: When resetting quad SPI, you must follow instructions specified in Resetting Quad SPI Flash on page 14.

Specifies one of the attached quad SPI devices via the chip select

lines. Takes a one-word argument as described below:

continued...

(7) This number does not include the command or response header.

Send Feedback

Mailbox Client Intel® FPGA IP User Guide 19

1. Mailbox Client Intel FPGA IP User Guide UG-20087 | 2021.11.10

Command QSPI_READ QSPI_WRITE QSPI_ERASE

Code Command Response (Hex) Length (7) Length (7)

Description

· Bits[31:28]: Flash device to select. The value 4'b0000 selects the flash that corresponds to nCSO[0]. nCSO[0] is the only signal that the FPGA can use to access the quad SPI flash device.
· Bits[27:0]: Reserved (write as 0).
Note: The HPS can use nCSO[3:1] to access 3 additional quad SPI devices.
This command is optional for the AS x4 configuration scheme, the chip select line follows the last executed QSPI_SET_CS command or defaults to nCSO[0] after the AS x4 configuration. The JTAG configuration scheme requires executing this command to access the QSPI flash that connects the SDM_IO pins.
Access to the QSPI flash memory devices using SDM_IO pins is only available for the AS x4 configuration scheme, JTAG configuration, and a design compiled for AS x4 configuration. For the Avalon streaming interface (Avalon ST) configuration scheme, you must connect QSPI flash memories to GPIO pins.
Important: When resetting quad SPI, you must follow instructions specified in Resetting Quad SPI Flash on page 14.

Reads the attached quad SPI device. The maximum transfer size is 4

kilobytes (KB) or 1024 words.

Takes two arguments:

· The quad SPI flash address (one word). The address must be word aligned. The device returns the 0x1 error code for nonaligned addresses.

· Number of words to read (one word).

When successful, returns OK followed by the read data from the quad SPI device. A failure response returns an error code.

For a partially successful read, QSPI_READ may erroneously return the OK status.

Note: You cannot run the QSPI_READ command while device configuration is in progress.

Important: When resetting quad SPI, you must follow instructions specified in Resetting Quad SPI Flash on page 14.

2+N

Writes data to the quad SPI device. The maximum transfer size is 4

kilobytes (KB) or 1024 words.

Takes three arguments:

· The flash address offset (one word). The write address must be word aligned.

· The number of words to write (one word).

· The data to be written (one or more words).

A successful write returns the OK response code.

To prepare memory for writes, use the QSPI_ERASE command before issuing this command.

Note: You cannot run the QSPI_WRITE command while device configuration is in progress.

Important: When resetting quad SPI, you must follow instructions specified in Resetting Quad SPI Flash on page 14.

Erases a 4/32/64 KB sector of the quad SPI device. Takes two

arguments:

continued...

(7) This number does not include the command or response header.
Mailbox Client Intel® FPGA IP User Guide 20

Send Feedback

1. Mailbox Client Intel FPGA IP User Guide UG-20087 | 2021.11.10

Command
QSPI_READ_ DEVICE_REG QSPI_WRITE_ DEVICE_REG
QSPI_SEND_ DEVICE_OP

Code Command Response (Hex) Length (7) Length (7)

Description

· The flash address offset to start the erase (one word). Depending on the number of words to erase, the start address must be: -- 4 KB aligned if number words to erase is 0x400 -- 32 KB aligned if number words to erase is 0x2000 -- 64 KB aligned if number words to erase is 0x4000 Returns an error for non-4/32/64 KB aligned addresses.
· The number of words to erase is specified in multiples of: -- 0x400 to erase 4 KB (100 words) of data. This option is the minimum erase size. -- 0x2000 to erase 32 KB (500 words) of data -- 0x4000 to erase 64 KB (1000 words) of data
A successful erase returns the OK response code.
Important: When resetting quad SPI, you must follow instructions specified in Resetting Quad SPI Flash on page 14.

Reads registers from the quad SPI device. The maximum read is 8

bytes. Takes two arguments:

· The opcode for the read command.

· The number of bytes to read.

A successful read returns the OK response code followed by the data read from the device. The read data return is in multiple of 4 bytes. If the bytes to read is not an exact multiple of 4 bytes, it is padded with multiple of 4 bytes until the next word boundary and the padded bit value is zero.

Important: When resetting quad SPI, you must follow instructions specified in Resetting Quad SPI Flash on page 14.

2+N

Writes to registers of the quad SPI. The maximum write is 8 bytes.

Takes three arguments:

· The opcode for the write command.

· The number of bytes to write.

· The data to write.

To perform a sector erase or sub-sector erase, you must specify the serial flash address in most significant byte (MSB) to least significant byte (LSB) order as the following example illustrates.

To erase a sector of a Micron 2 gigabit (Gb) flash at address 0x04FF0000 using the QSPI_WRITE_DEVICE_REG command, write the flash address in MSB to LSB order as shown here:

Header: 0x00003036

Opcode: 0x000000DC

Number of bytes to write: 0x00000004

Flash address: 0x0000FF04

A successful write returns the OK response code. This command pads data that is not a multiple of 4 bytes to the next word boundary. The command pads the data with zero.

Important: When resetting quad SPI, you must follow instructions specified in Resetting Quad SPI Flash on page 14.

Sends a command opcode to the quad SPI. Takes one argument:

· The opcode to send the quad SPI device. A successful command returns the OK response code.

continued...

(7) This number does not include the command or response header.

Send Feedback

Mailbox Client Intel® FPGA IP User Guide 21

1. Mailbox Client Intel FPGA IP User Guide UG-20087 | 2021.11.10

Command REBOOT_HPS

Code Command Response (Hex) Length (7) Length (7)

Description

Important: When resetting quad SPI, you must follow instructions specified in Resetting Quad SPI Flash on page 14.

Triggers the HPS cold reset. Firmware loads the new bitstream from

the boot source based on MSEL settings. The loaded bitstream and

your device must use the same firmware version. When loading the

new bitstream, SDM wipes HPS and loads the HPS bootloader to HPS

OCRAM and releases MPU.

Refer to Intel Stratix 10 Hard Processor System Technical Reference Manual and Intel Stratix 10 SoC FPGA Boot User Guide for more details on HPS reset.

For CONFIG_STATUS and RSU_STATUS major and minor error code descriptions, refer to Appendix: CONFIG_STATUS and RSU_STATUS Error Code Descriptions.
Related Information
· Appendix A: CONFIG_STATUS and RSU_STATUS Error Code Descriptions
· Intel Stratix 10 Analog to Digital Converter User Guide For more information about the temperature sensor channel numbers and temperature sensing diodes (TSDs).
· Intel Stratix 10 Hard Processor System Technical Reference Manual
· Intel Stratix 10 FPGA Boot User Guide · Intel eASICTM N5X Hard Processor System Remote System Update User Guide
For more information about version fields.
· Intel Agilex Power Management User Guide For more information about the temperature sensor channel numbers and temperature sensing diodes (TSDs).
· Intel Agilex Hard Processor System Technical Reference Manual
· Intel Agilex Hard Processor System Remote System Update User Guide

1.5.2. Error Code Responses

Table 12. Error Codes

Value (Hex)

Error Code Response

INVALID_COMMAND

UNKNOWN_COMMAND

INVALID_COMMAND_

PARAMETERS

COMMAND_INVALID_ON_

SOURCE

Description
Indicates that the command completed successfully. A command may erroneously return the OK status if a command, such as QSPI_READ is partially successful. Indicates that the currently loaded boot ROM cannot decode or recognize the command code. Indicates that the currently loaded firmware cannot decode the command code. Indicates that the command is incorrectly formatted. For example, the length field setting in header is not valid.
Indicates that the command is from a source for which it is not enabled.
continued...

(7) This number does not include the command or response header.

Mailbox Client Intel® FPGA IP User Guide 22

Send Feedback

1. Mailbox Client Intel FPGA IP User Guide UG-20087 | 2021.11.10

Value (Hex)
8

Error Code Response CLIENT_ID_NO_MATCH

INVALID_ADDRESS

AUTHENTICATION_FAIL

TIMEOUT

HW_NOT_READY

HW_ERROR

80 - 8F COMMAND_SPECIFIC_ ERROR

100 NOT_CONFIGURED

Description

Indicates that the Client ID cannot complete the request to close the exclusive access to quad SPI. The Client ID does not match the existing client with the current exclusive access to quad SPI.

The address is invalid. This error indicates one of the following conditions: · An unaligned address · An address range problem · A read permission problem · An invalid chip select value, displaying value of more than 3 · An invalid address in RSU case · An invalid bitmask value for GET_VOLTAGE command · An invalid page selection for GET_TEMPERATURE command

Indicates the configuration bitstream signature authentication failure.

This error indicates time out due to the following conditions: · Command · Waiting for QSPI_READ operation to complete · Waiting for the requested temperature reading from one of the temperature
sensors. May indicate a potential hardware error in the temperature sensor.

Indicates one of the following conditions: · The hardware is not ready. Can indicate either an initialization or configuration
problem. The hardware may refer to quad SPI. · RSU image is not used to configure the FPGA.

Indicates that the command completed unsuccessfully due to unrecoverable hardware error.

Indicates a command specific error due to an SDM command you used.

SDM Command

Error Name

Error Description code

GET_CHIPID

EFUSE_SYSTEM_ FAILURE

0x82

Indicates that the eFuse cache pointer is invalid.

QSPI_OPEN/ QSPI_CLOSE/ QSPI_SET_CS/ QSPI_READ_D EVICE_REG/ QSPI_WRITE_ DEVICE_REG/ QSPI_SEND_D EVICE_OP/ QSPI_READ

QSPI_HW_ERROR
QSPI_ALREADY_ OPEN

0x80 0x81

Indicates QSPI flash memory error. This error indicates one of the following conditions:
· A QSPI flash chip select setting problem
· A QSPI flash initialization problem
· A QSPI flash resetting problem
· A QSPI flash settings update problem
Indicates that the client's exclusive access to QSPI flash via QSPI_OPEN command is already open.

Indicates that the device is not configured.

continued...

Send Feedback

Mailbox Client Intel® FPGA IP User Guide 23

1. Mailbox Client Intel FPGA IP User Guide UG-20087 | 2021.11.10

Value (Hex)
1FF
2FF
3FF

Error Code Response
ALT_SDM_MBOX_RESP_ DEVICE_ BUSY
ALT_SDM_MBOX_RESP_NO _ VALID_RESP_AVAILABLE ALT_SDM_MBOX_RESP_ ERROR

Description
Indicates that the device is busy due to following use cases: · RSU: Firmware is unable to transition to different version due to an internal
error. · HPS: HPS is busy when in HPS reconfiguration process or HPS cold reset. Indicates that there is no valid response available.
General Error.

1.5.3. Error Code Recovery

The table below describes possible steps to recover from an error code. Error recovery depends on specific use case.

Table 13.
Value 4 6 8 9
B
C 80 81

Error Code Recovery for known Error Codes

Error Code Response INVALID_COMMAND_ PARAMETERS
COMMAND_INVALID_ ON_SOURCE

Error Code Recovery
Resend the command header or header with arguments with corrected parameters. For example, ensures that the length field setting in header is sent with the correct value.
Resend the command from valid source such as JTAG, HPS, or core fabric.

CLIENT_ID_NO_MATCH INVALID_ADDRESS
TIMEOUT
HW_NOT_READY QSPI_HW_ERROR QSPI_ALREADY_OPEN

Wait for the client who opened the access to quad SPI to complete its access and then closes the exclusive access to quad SPI.

Possible error recovery steps: For GET_VOLTAGE command: Send command with a valid bitmask. For GET_TEMPERATURE command: Send command with valid sensor location and sensor mask. For QSPI operation: · Send command with a valid chip select. · Send command with a valid QSPI flash address. For RSU: Send command with a valid start address of the factory image or application.

Possible recovery steps:
For GET_TEMPERATURE command: Retry to send the command again. If problem persists, reconfigure or power cycle the device.
For QSPI operation: Check signal integrity of QSPI interfaces and attempt command again.
For HPS restart operation: Retry to send the command again.

Possible recovery steps: For QSPI operation: Reconfigure the device via source. Ensure that IP used to build your design allows access to the QSPI flash. For RSU: Configure the device with RSU image.

Check the QSPI interface signal integrity and to ensure the QSPI device is not damaged.

Client already opened QSPI. Continue with the next operation.

continued...

Mailbox Client Intel® FPGA IP User Guide 24

Send Feedback

1. Mailbox Client Intel FPGA IP User Guide UG-20087 | 2021.11.10

Value 82

Error Code Response EFUSE_SYSTEM_FAILURE

100 NOT_CONFIGURED
1FF ALT_SDM_MBOX_RESP_ DEVICE_ BUSY

Error Code Recovery
Attempt reconfiguration or power cycle. If error persists after reconfiguration or power cycle, the device may be damaged and unrecoverable.
Send a bitstream that configures the HPS.
Possible error recovery steps: For QSPI operation: Wait for ongoing configuration or other client to complete operation. For RSU: Reconfigure device to recover from internal error. For HPS restart operation: Wait for reconfiguration via HPS or HPS Cold Reset to complete.

1.6. Specifying the Command and Response FIFO Depths
The optimal depth of the command and response FIFOs depends on the specific application. You should size these FIFOs to accommodate the maximum command and responses that your application requires.
The following example illustrates this point. Consider an application sends a maximum of eight back-to-back GET_TEMPERATURE commands to the FPGA core and one transceiver bank. Each command consists of a header and one command argument, specifying the mask of the temperature sensors to read. The optimal setting for the command FIFO is 16 words.
For the response FIFO, each response has one header word, and one word each for the core temperature and transceiver bank temperature. Each response is three words. The optimal setting for the response FIFO Depth is 24 words.
1.7. Enabling Cryptographic Services
The cryptographic offloading feature is available for Intel Agilex devices in Intel Quartus Prime Pro Edition software version 21.3 or later.
To enable this feature in the IP parameter editor, set HAS_OFFLOAD parameter to 1. When enabled, the Mailbox Client IP generates an AXI 64-bit target interface as well as a cryptographic fabric IP instantiated by a debug fabric. The connection between the mailbox client interface and the mailbox fabric interface are done using the autogenerated debug fabric module in the Intel Quartus Prime software. The SDM uses mailbox client to read and write data from the user space memory.
For more information about the cryptographic services, refer to Intel Agilex Device Security User Guide.
Related Information Intel Agilex Device Security User Guide

Send Feedback

Mailbox Client Intel® FPGA IP User Guide 25

1. Mailbox Client Intel FPGA IP User Guide UG-20087 | 2021.11.10

1.8. Using the Mailbox Client Intel FPGA IP
Writing Command Packet Figure 4. Flow Chart for Writing Command Packet
Start No

Read Base + 2 Command FIFO empty
space available (n) > 0 ?
Yes

Total

Command length (t)

> 0 ?

Yes

Write command to base + 0 for (n) times.
Set t = t - n

Command FIFO empty space available (n) >
Total Command length (t)

Yes
Write command with one word (header and/or arguments) to base + 0
for (t-1) times

Write last argument or header (command with
no arguments) to base + 1

End
Agenda: n: Command FIFO empty space t: Total Command Length
Write Command Description
When you send a command to the SDM, write the command word into command register, which is the base address. To stay in sync with the hardware, while the command length (t) is greater than zero, write the header and arguments in the Command register which is (base address + 0). Continue writing the header and/or

Mailbox Client Intel® FPGA IP User Guide 26

Send Feedback

1. Mailbox Client Intel FPGA IP User Guide UG-20087 | 2021.11.10
arguments, one word at the time, in the Command register (base address + 0) while there is available free space in the FIFO for commands (n > t). Write the last word to the Command last word register which is (base address +1). For commands with no arguments, write the header to the Command last word register, (base address +1).
Reading from (base address + 2) shows the remaining available free space in the FIFO for commands. The command FIFO can become full when the SDM is busy. The IP requires 3 clock cycles to update the Command FIFO empty space value. You can begin reading the Command FIFO empty space value 3 clock cycles after writing the command to the IP.
You must check the Command FIFO empty space register, (base address + 2) before proceeding to write into the Command/Command last word registers. The behavior of the IP is undefined if you write to (base address + 0) and (base address + 1) while the FIFO is full. The write data is discarded.
Unexpected or undefined behavior may occur if you send more commands than required. For example, send the following commands to read the Chip ID value: · Write the command header to (base address + 0). · Write again the command header to (base address + 1).
In the above scenario, the IP core expects a 3-word response (command header and 2 data words). However, the SDM only returns a one-word response, which is the error response code.
You must send commands in the correct order to the Command or Command last word register, as described in the Writing Command Packet on page 26. Failure to send commands in the correct order can result in loss of services for all mailbox clients, including the following standalone IP cores: · Temperature Sensor Intel FPGA IP · Voltage Sensor Intel FPGA IP · Chip ID Intel FPGA IP · Advanced SEU Detection Intel IP · Partial Reconfiguration Controller Intel IP · Partial Reconfiguration External Configuration Controller Intel FPGA IP

Send Feedback

Mailbox Client Intel® FPGA IP User Guide 27

1. Mailbox Client Intel FPGA IP User Guide UG-20087 | 2021.11.10

Figure 5.

Reading Response Packet
Flow Chart for Reading Response Packet
Start No

Read Base + 8 ISR = 1?
Yes
Read base + 6 SOP = 1 and response FIFO fill level (n) > 0?
Yes
Read base + 5 Error code = 0?
Yes

Refer to Error Codes and Error Code Recovery

tables for error details

Length of

response header (t) > 0?

Yes

Read base + 6 Response FIFO fill level (n) > 0?

Yes

Read base + 5 n times

and set new length of

response header.

Set t = t- n

Response FLIeFnOgftinlhl >loefv=reelts(pno)n>se=
header (t)?
Yes

Read base + 5 for (t-1) times to retrieve the response data

Yes

Agenda: n: Response FIFO fill level t: Length of the response header

End oRfePaandck>beat=s(eEtO+P6) = 1?
Yes Read base + 5 to retrieve the last response data
End

Read Command Description
1. Read (base address + 8) to check if bit 0 of Interrupt status register is 1, to indicate the valid data is available for the master to read. You can poll the Interrupt status register continuously until bit 0 is 1.
2. Read (base address + 6) to check the SOP (start of packet), EOP (end of packet), and the Response FIFO fill level (n).

Mailbox Client Intel® FPGA IP User Guide 28

Send Feedback

1. Mailbox Client Intel FPGA IP User Guide UG-20087 | 2021.11.10
To read multiple words, complete the following steps:
a. If SOP = 1 and EOP = 0, the response has multiple words.
b. If the Response FIFO fill level (n) is non-zero, the FIFO has valid data.
c. For example, if you perform a QSPI_READ operation to read 10 words from quad SPI flash, a return value of 0x0000002d indicates that the SDM wrote 11 words to the response FIFO. The 11 words comprise a response header word and 10 data words.
To read a single word, complete the following steps:
a. If SOP = 1 and EOP = 1, the response has a single word.
b. If the Response FIFO fill level is non-zero, the FIFO has valid data.
c. A return value of 0x00000007 indicates that the SDM wrote a single word to the response FIFO. This single is both the start and end of the single-cycle packet.
3. Read the response header at (base address + 5). The LENGTH value specifies the number of words in the response. Proceed to step 4 if the response error code is zero. The response error code is non-zero for unsuccessful commands. Refer to Table 12 on page 22 for more information.
4. When the length of the response header (t) is greater than zero (LENGTH > 1) , read (base address + 5) to retrieve the response data. While continuously reading the response data, you must also continuously poll (base address + 6) to check the Response FIFO fill level (n). For the final word of the packet, the Response FIFO fill level (n) and EOP value are expected to be 1 at the same time. You must check for EOP = 1 before proceeding to read the final word from the response data.
Note: If the response FIFO is empty, the return data is undefined. You must check the Interrupt status register to ensure that valid data is available. You must verify that the Response FIFO fill level (n) is non-zero before reading the response data.
Ensure that you read or flush out the content in the response FIFO before issuing a new command to the mailbox. Continuously sending commands without reading back the valid data from the response FIFO gradually fills the response FIFO. When the response FIFO overflows the SDM freezes.
If the SDM freezes you must reconfigure the device. The Intel Quartus Prime software supports device reconfiguration starting in version 19.1. For earlier versions of the Intel Quartus Prime software, power cycle the device to recover.
Restrictions
1. You can only issue one request and read back the response before issuing a new request to the Mailbox Client IP. Wait 10 ms between back-to-back commands to the SDM mailbox.
2. Do not instantiate more than six mailbox clients in your design. For designs requiring more than six mailbox clients, use the Mailbox Client IP to replace the following standalone IP cores:

Send Feedback

Mailbox Client Intel® FPGA IP User Guide 29

1. Mailbox Client Intel FPGA IP User Guide UG-20087 | 2021.11.10

· Voltage Sensor Intel FPGA IP · Chip ID Intel FPGA IP · Serial Flash Mailbox Client Intel FPGA IP · Temperature Sensor Intel FPGA IP

Attention:

Starting in version 19.2 of the Intel Quartus Prime software, a restriction applies to the following mailbox client IPs that access the SDM mailbox over an Avalon MemoryMapped (Avalon-MM) interface: · Temperature Sensor · Voltage Sensor · Chip ID · Serial Flash Mailbox Client · Mailbox Client IP · Advanced SEU Detection IP · Partial Reconfiguration IP

If you use the Mailbox IP in designs compiled in Intel Quartus Prime Pro Edition software version 19.2 or later, you must only use SDM firmware starting from version 19.2 or later to configure the FPGA.

1.9. Mailbox Client Intel FPGA IP Core Use Case Examples
The Mailbox Client Intel FPGA IP is an Avalon MM slave component that must connect to an Avalon MM master. The simplest Avalon MM master is the JTAG-to-Avalon Master.
The rsu1.tcl script provides examples to perform all the available command functions. You can run the functions available in the rsu1.tcl script via System Console of the Intel Quartus Prime software.
The following example shows how to access the quad SPI flash memory. Follow this sequence to prevent errors. Refer to Table 11 on page 15 for more information about these commands. 1. QSPI_OPEN 2. QSPI_SET_CS 3. Any of the following quad SPI operations:
· QSPI_READ · QSPI_WRITE · QSPI_ERASE · QSPI_READ_DEVICE_REG · QSPI_WRITE_DEVICE_REG · QSPI_SEND_DEVICE_OP 4. QSPI_CLOSE

Mailbox Client Intel® FPGA IP User Guide 30

Send Feedback

1. Mailbox Client Intel FPGA IP User Guide UG-20087 | 2021.11.10
Related Information Example of Tcl Script
A Tcl script that implements all the Mailbox Client operations.

Send Feedback

Mailbox Client Intel® FPGA IP User Guide 31

1. Mailbox Client Intel FPGA IP User Guide UG-20087 | 2021.11.10

1.10. Nios II HAL Driver
This section describes the HAL driver for the Mailbox Client Intel FPGA IP core. Intel provides HAL system library drivers that enable you to perform Mailbox Client operations using the HAL API functions. The operations along with their descriptions are listed in Table 11 on page 15. In addition, the HAL driver also provides exclusive functions on QSPI flash device-related operations to simplify your design flow.
The HAL API is available for this controller in the following software files: · altera_s10_mailbox_client.h
· altera_s10_mailbox_client.c
· altera_s10_mailbox_client_flash.h
· altera_s10_mailbox_client_flash.c
These files implement the Mailbox Client core device driver for the HAL system library.
To use the HAL API, enable altera_safeclib in the BSP Software Package from BSP Editor. Enter mailbox_client_open() function to start the HAL API. Note that the interrupt connection to the processor is necessary to use the HAL API.
The absolute addressing to the quad SPI memory specifies all the offset-related variables. You must complete the quad SPI operation by calling mailbox_client_flash_open() before any flash operation, and mailbox_client_flash_close() at the end of any flash operation.
Related Information · Nios II Software Developer Handbook: Using Flash Device
For more information about using flash devices. · Nios II Configuration and Booting Solutions
For more information about booting Nios II from flash. · Example of HAL API Application
A .c source code that implements the Mailbox Client Nios II HAL Driver.

1.10.1. Driver API

Table 14. mailbox_client_open

Prototype:

mailbox_client_open(const char *name)

Include:

<altera_s10_mailbox_client.h>

Parameter:

· name character pointer to name of Mailbox Client Intel FPGA peripheral as registered with the HAL

Return:

Return non-NULL if successful and otherwise return: · -NULL for Invalid argument. Found no device or wrong input name

Description:

Retrieve a pointer to the Mailbox Client block instance. Search for the list of registered mailbox client instances for the one with the supplied name.

Mailbox Client Intel® FPGA IP User Guide 32

Send Feedback

1. Mailbox Client Intel FPGA IP User Guide UG-20087 | 2021.11.10

Table 15. mailbox_client_send_cmd

Prototype:

mailbox_client_send_cmd (intel_mailbox_client* fd, alt_u8 id, alt_u32 cmd, alt_u32* arg, int
arg_length, int cmd_length, alt_u32* input_data, alt_u32* resp_buf, alt_u32 resp_buf_len)
(11)

Include: Parameter:
Return:
Description:

<altera_s10_mailbox_client.h>
· fd pointer to the flash device structure · id - command ID · cmd - mailbox client command · arg - mailbox Client argument(12) · arg_length - number of arguments · cmd_length - command length (arg_length + input_data length) · input_data - input data · resp_buf - response buffer · res_buf_len - response buffer length
Return 0 if successful and otherwise return: · error codes for mailbox client in Table 12 on page 22 · -EINVAL for Invalid argument · -ETIME for polling timeout and skipping the loop after 5 seconds · -EBACK_TOUT for back pressure timer interrupt(13) · -EEOP_TOUT for end of packet timer interrupt(14) · -ECMD_INVLD for invalid command interrupt · -ENOBUFS for the response buffer length is insufficient(15) · -ENOSYS for unmatched returned command ID from SDM
Send commands and data to the Mailbox Client. Reads back the response when data valid interrupt occurs. For more information, refer to Example 1 in Driver API Application on page 0.

Table 16. mailbox_client_flash_open

Prototype:

mailbox_client_flash_open(intel_mailbox_client* fd)

Include:

<altera_s10_mailbox_client_flash.h>

Parameter:

· fd pointer to the flash device structure

Return:

Return 0 if successful and otherwise return: · -EINVAL for Invalid argument · -ENODEV for unrecognized flash device

Description:

Send command to the mailbox client for QSPI open and QSPI chip select. Provides exclusive access to the quad SPI interface. Determines the QSPI flash size.

(11) Prior to Intel Quartus Prime Pro Edition software version 21.3, the response buffer length (resp_buf_len) was declared as a pointer rather than an integer.
(12) Argument represents the parameters needed for mailbox client operation, not including input data.
(13) The recommended error code recovery is the full system reconfiguration.
(14) The recommended error code recovery is to reset the Mailbox Client Intel FPGA IP.
(15) If the response buffer length is insufficient, the HAL API discards the collected data from Mailbox Client Intel FPGA IP and return ENOBUFS.

Send Feedback

Mailbox Client Intel® FPGA IP User Guide 33

1. Mailbox Client Intel FPGA IP User Guide UG-20087 | 2021.11.10

Table 17. mailbox_client_flash_close

Prototype: Include: Parameter: Return:
Description:

mailbox_client_flash_close(intel_mailbox_client* fd)
<altera_s10_mailbox_client_flash.h>
· fd pointer to the flash device structure
Return 0 if successful and otherwise return: · -EINVAL for Invalid argument
Send command to the mailbox client for QSPI close. Stops the exclusive access to the quad SPI interface.

Table 18. mailbox_client_flash_get_info

Prototype: Include: Parameter:
Return:
Description:

mailbox_client_flash_get_info(intel_mailbox_client* fd, flash_region** info, int* number_of_regions)
<altera_s10_mailbox_client_flash.h>
· fd pointer to the flash device structure · info - pointer to the flash region · number_of_regions - pointer to the number of regions
Return 0 if successful and otherwise return: · -EINVAL for Invalid argument · -EIO for possible hardware issue
Provide information corresponding to nCSO[0]. Returns the flash memory offset, flash memory size, number of flash device, number of sector, and sector size values.

Table 19. mailbox_client_flash_read

Prototype: Include: Parameter:
Return: Description:

mailbox_client_flash_read (intel_mailbox_client* fd, int offset, void* dest_addr, int length)
<altera_s10_mailbox_client_flash.h>
· fd pointer to the flash device structure · offset - read flash address (unaligned access) · dest_addr - destination buffer (in byte size) · length - size of read data (in byte size)
Return 0 if successful and otherwise return: · -EINVAL for Invalid argument
Read data from selected address specified by the length in byte size. Length is a non-zero value.

Table 20. mailbox_client_flash_erase_block

Prototype: Include: Parameter: Return:
Description:

mailbox_client_flash_erase_block (intel_mailbox_client* fd, int block_offset)
<altera_s10_mailbox_client_flash.h>
· fd pointer to the flash device structure · block_offset - address offset from the start of flash sector specified to be erased
Return 0 if successful and otherwise return: · -EINVAL for Invalid argument · -EIO for erase failed and sector might be protected
Erase a single flash sector.

Mailbox Client Intel® FPGA IP User Guide 34

Send Feedback

1. Mailbox Client Intel FPGA IP User Guide UG-20087 | 2021.11.10

Table 21. mailbox_client_flash_write_block

Prototype: Include: Parameter:
Return: Description:

mailbox_client_flash_write_block (intel_mailbox_client* fd, int block_offset, int data_offset, const void* data, int length)
<altera_s10_mailbox_client_flash.h>
· fd pointer to the flash device structure · block_offset - sector address. Starts at the flash sector specified to be written to · data_offset - byte offset (unaligned access) of write into memory · data - data buffer to be written (in byte size) · length - size of write data (in byte size)
Return 0 if successful and otherwise return: · -EINVAL for Invalid argument
Write one block or sector of data into the flash. The write data length cannot split between adjacent sectors. The function assumes the address is empty. You must erase it prior its programming.

Table 22. mailbox_client_flash_write

Prototype:

mailbox_client_flash_write (intel_mailbox_client* fd, int offset, const void* src_addr, int length)

Include:

<altera_s10_mailbox_client_flash.h>

Parameter:

· fd pointer to the flash device structure · offset - flash address (unaligned access) of write to the flash memory · src_addr - source buffer (in byte size) · length - size of write data (in byte size)

Return:

Return 0 if successful and otherwise return: · -EINVAL for Invalid argument

Description:

Program the data into the flash at the selected address. Automatically erase the block as needed before programming.

Related Information Error Code Responses on page 22

Send Feedback

Mailbox Client Intel® FPGA IP User Guide 35

1. Mailbox Client Intel FPGA IP User Guide UG-20087 | 2021.11.10

1.11. Mailbox Client Intel FPGA IP User Guide Archives
IP versions are the same as the Intel Quartus Prime Design Suite software versions up to v19.1. From Intel Quartus Prime Design Suite software version 19.2 or later, IP cores have a new IP versioning scheme.
If an IP core version is not listed, the user guide for the previous IP core version applies.

Intel Quartus Prime Version 21.2 21.1 20.4 20.3 20.2 20.1 19.3 18.1 17.1

IP Core Version
20.0.2 20.0.2 20.0.0 20.0.0 20.0.0 20.0.0 19.1 18.1 17.1

User Guide
Mailbox Client Intel FPGA IP User Guide Mailbox Client Intel FPGA IP User Guide Mailbox Client Intel FPGA IP User Guide Mailbox Client Intel FPGA IP User Guide Mailbox Client Intel FPGA IP User Guide Mailbox Client Intel FPGA IP User Guide Mailbox Client Intel FPGA IP User Guide Mailbox Client Intel FPGA IP User Guide Mailbox Client Intel FPGA IP User Guide

Mailbox Client Intel® FPGA IP User Guide 36

Send Feedback

1. Mailbox Client Intel FPGA IP User Guide UG-20087 | 2021.11.10

1.12. Document Revision History for the Mailbox Client Intel FPGA IP User Guide

Document Version 2021.11.10
2021.06.21
2021.03.29 2020.12.14

Intel Quartus Prime Version
21.3
21.2
21.1
20.4

Changes

Made the following changes: · Updated the device family support for Intel Agilex devices. · Added new section describing support for cryptographic services. · Revised Interrupt Enable Register table. Added new registers:
-- EN_CRYPTO_MEMORY_TIMEOUT -- EN_CRYPTO_ERROR_RECOVERY_PROGRESS · Revised Interrupt Status Register table. Added new interrupts: -- CRYPTO_MEMORY_TIMEOUT -- CRYPTO_ERROR_RECOVERY_PROGRESS · Revised Command List and Description table. Updated description for: -- CONFIG_STATUS -- RSU_STATUS · Updated the mailbox_client_send_cmd command in the Driver API section. -- Revised response buffer length declaration from a pointer (alt_u32*
resp_buf_len) to an integer (alt_u32 resp_buf_len). -- Added an ENOBUFS-related footnote.

Made the following changes: · Revised Interrupt Enable Register. Added note about enable bits. · Revised Command List and Description table. Updated description for:
-- RSU_STATUS
-- QSPI_OPEN
-- QSPI_SET_CS
-- QSPI_ERASE
· Revised Read Command Description in the Using the Mailbox Client Intel FPGA IP. Added attention note about accessing SDM over an Avalon memory-mapped interface.
· Revised Nios II HAL Driver. Added text about absolute addressing to the quad SPI.
· Added mailbox_client_flash_get_info operation in the Driver API section.
· Removed Driver API Application topic. The content was moved to a file referenced in the Driver API section.
· Updated Appendix: CONFIG_STATUS and RSU_STATUS Error Code Descriptions. Added 0xD00D - 0xD013 minor error codes descriptions.

Made the following changes: · Revised the Flow Chart for Response Packet figure and the Read
Command Description section. · Revised RSU_IMAGE_UPDATE description in the Command List and
Description table. · Added new topics:
-- Nios II HAL Driver -- Driver API -- Driver API Application · Restructured Operation Commands. Moved major and minor error code descriptions for the CONFIG_STATUS and RSU_STATUS commands to the Appendix: CONFIG_STATUS and RSU_STATUS Error Code Descriptions.

Made the following changes:

continued...

Send Feedback

Mailbox Client Intel® FPGA IP User Guide 37

1. Mailbox Client Intel FPGA IP User Guide UG-20087 | 2021.11.10

Document Version
2020.10.05 2020.06.30 2020.04.13

Intel Quartus Prime Version
20.3 20.2
20.1

Changes

· Revised block diagram description in the Mailbox Client Intel FPGA IP User Guide topic.
· Updated the Mailbox Client Intel FPGA IP System Block Diagram figure. The figure depicts various ways to communicate with Mailbox Client IP.
· Added important note about resetting QSPI flash in the Operation Commands topic.
· Updated the Command List and Description table: -- Revised GET_TEMPERATURE command description. Clarified difference between Intel Stratix 10 and devices. -- Revised RSU_IMAGE_UPDATE command description.
· Added text about resetting QSPI flash. · Added text describing behavior between the external host and
FPGA. · Removed text: Returns a non-zero response if the device is
already processing a configuration command. -- Updated QSPI_WRITE and QSPI_READ descriptions to specify that
the maximum transfer size is 4 kilobytes or 1024 words. -- Corrected response length from 1 to 0 for the QSPI_OPEN,
QSPI_CLOSE and QSPI_SET_CS command.
-- Revised QSPI_OPEN, QSPI_WRITE, QSPI_READ_DEVICE_REG, and QSPI_WRITE_DEVICE_REG descriptions.
-- Added a new command: REBOOT_HPS.
· Added new topic: Error Code Recovery. · Revised Timer Registers topic. Added footnotes and updated registers
description. · Updated Flow Chart for Reading Response Packet figure.

Made the following changes: · Revised GET TEMPERATURE command description for Intel Agilex
devices in the Command List and Description table. · Added recommendation about the reset synchronizer in the Mailbox
Client FPGA Core Signals section. · Updated the Error Codes table. Added new error code responses:
-- HW_ERROR
-- COMMAND_SPECIFIC_ERROR

Made the following changes:
· Revised LENGTH and Command Code/Error Code descriptions in the Command and Response Header Description table.
· Revised GET_TEMPERATURE command description in the Command List and Description table.
· Removed UNKNOWN_BR command from the Error Codes table.
· Added new timer feature to handle the error detection for the incomplete transaction timeout error and the SDM backpressure timeout fatal error.
· Added support for an EOP_TIMEOUT interrupt which indicates that the full command did not include the EOP.
· Added support for a BACKPRESSURE_TIMEOUT interrupt which indicates that an error within the SDM occurred.
· Removed SD/MMC text from the CLIENT_ID_NO_MATCH description in the Error Codes table.
· Updated write and read command descriptions in the Using the Mailbox Client Intel FPGA IP section.

Made the following changes:

continued...

Mailbox Client Intel® FPGA IP User Guide 38

Send Feedback

1. Mailbox Client Intel FPGA IP User Guide UG-20087 | 2021.11.10

Document Version
2020.03.17 2019.09.30

Intel Quartus Prime Version
19.3 19.3

Changes
· Added the following restriction to the definition of QSPI_SET_CS: Access to the QSPI flash memory devices using SDM_IO pins is only available for the AS x4 configuration scheme, JTAG configuration, and a design compiled for ASx4 configuration. For the Avalon ST configuration scheme, you must connect QSPI flash memories to GPIO pins.
· Added the following text to the definition of the Failing image field of the RSU_STATUS command:
Note: A rising edge on nCONFIG to reconfigure from ASx4, does not clear this field. Information about failing image only updates when the Mailbox Client receives a new RSU_IMAGE_UPDATE command and successfully configures from the update image.
· Added RSU_NOTIFY command in the Command List and Description table.
· Revised the Flow Chart for Writing Command Packet and Flow Chart for Reading Response Packet to include the correct sequence for writing commands into a command FIFO and reading response packets from a response FIFO. Updated corresponding Write Command Description and Read Command Description sections.
Made the following changes: · Updated the Error Codes table:
-- Renamed INVALID_COMMAND_PARAMETERS to INVALID_LENGTH. -- Changed COMMAND_INVALID_ON_SOURCE hex value from 5 to 6. -- Changed CLIENT_ID_NO_MATCH hex value from 6 to 8. -- Changed INVALID_ADDRESS hex value from 7 to 9. -- Added AUTHENTICATION_FAIL command. -- Changed TIMEOUT hex value from 8 to B. -- Changed HW_NOT_READY hex value from 9 to C.
Made the following changes: · Added device support for the Intel Agilex device. · Added support for a COMMAND_INVALID interrupt which indicates the
command length specified in the header does not match the actual command sent. · Changed name of the IP from Mailbox Client Intel Stratix 10 FPGA IP to Mailbox Client Intel FPGA IP. · Revised introduction including the Figure 1: Mailbox Client Intel FPGA IP System Block Diagram. · Revised the Flow Chart for Writing Command Packet and Flow Chart for Reading Response Packet to include logic to handle multiple word commands and responses. · Changed references to names of all mailbox client IPs. The mailbox clients IP no longer include the Intel Stratix 10 FPGA in their names. · Added reference to AN 891: Using the Reset Release Intel FPGA IP. · Added reference to the Intel Agilex Power Management User Guide. · Updated the description of the GET_TEMPERATURE command to say the mask argument is optional. When omitted, the command returns the temperature for sensor 0. · Updated the RSU_STATUS command to say the highest priority failing image, not the last failing image. The error information is for the first failing image which is the highest priority failing image. · Added descriptions for CONFIG_STATUS and RSU_STATUS major and minor error codes.

Send Feedback

Mailbox Client Intel® FPGA IP User Guide 39

1. Mailbox Client Intel FPGA IP User Guide UG-20087 | 2021.11.10

Document Version

Intel Quartus Prime Version

Changes
· Added HPS_COLDRESET and HPS_WARMRESET to the list of soft functions for the CONFIG_STATUS command.
· Added Mailbox Client Intel FPGA IP User Guide Archives topic. · Added the following Intel FPGA IPs to the list of IPs that require proper
use of the Command and Command last registers: -- Advanced SEU Detection Intel IP -- Partial Reconfiguration Controller Intel IP -- Partial Reconfiguration External Configuration Controller Intel FPGA
IP -- Edited entire user guide for clarity and style.

Document Version
2019.04.19
2019.03.14 2019.02.25

Changes
· Updated the Feature Description topic. · Added a note to Figure: Command and Response Header Format. · Updated Table: Mailbox Client Intel Stratix 10 FPGA IP Command and Response Header Description
to update the description for bit[11] of the command and response header. · Updated Table: Command List and Description to update the descriptions for CONFIG_STATUS and
RSU_STATUS. · Renamed topic title Mailbox Client Intel Stratix 10 FPGA IP Core Avalon-MM Interface to Mailbox
Client Intel Stratix 10 FPGA IP Core Signals. · Renamed table title Mailbox Client Intel Stratix 10 FPGA IP Core Avalon-MM Interface to Mailbox
Client Intel Stratix 10 FPGA IP Core Signal Description. · Updated Table: Mailbox Client Intel Stratix 10 FPGA IP Core Signal Description to include
information on clock and reset signals. · Updated Table: Mailbox Client Intel Stratix 10 FPGA IP Core Avalon-Memory Map to remove urgent
command and urgent FIFO empty space. · Updated the Using the Mailbox Client Intel Stratix 10 FPGA IP Core topic:
-- Added new Figures: Flow Chart for Writing Command Packet and Flow Chart for Reading Response Packet.
-- Added a new section--Restrictions. -- Updated the description in the Writing Command Packet section. · Updated the Mailbox Client Intel Stratix 10 FPGA IP Core Use Case Examples topic. · Made editorial updates throughout the document.
· Updated the Mailbox Client Intel Stratix 10 FPGA IP Core User Guide topic. · Updated Figure: Mailbox Client Intel Stratix 10 FPGA IP Core and System Block Diagram. · Updated Table: Command List and Description:
-- Updated the column name Number of Commands to Command Length. -- Updated the column name Number of Responses to Respond Length. -- Corrected the description for QSPI_READ, QSPI_WRITE, and QSPI_ERASE.
· Updated the description in the Mailbox Client Intel Stratix 10 FPGA IP Core User Guide topic. · Updated Figure: Mailbox Client Intel Stratix 10 FPGA IP Core User Guide. · Updated Table: Interrupt Status Register to update the description for DATA_VALID. · Renamed the following topic titles:
-- Commands and Error Codes to Commands and Responses -- Commands to Operation Commands. · Updated Table: Mailbox Client Intel Stratix 10 FPGA IP Command and Response Header Description to update the descriptions for Length and Command Code/Error Code. · Updated Table: Command List and Description: -- Updated the number of responses and description for CONFIG_STATUS. -- Updated the number of responses for RSU_STATUS. -- Updated the descriptions for QSPI_READ, QSPI_WRITE, and QSPI_ERASE.
continued...

Mailbox Client Intel® FPGA IP User Guide 40

Send Feedback

1. Mailbox Client Intel FPGA IP User Guide UG-20087 | 2021.11.10

Document Version
2018.10.15
2018.02.14

Changes
· Updated Table: Mailbox Client Intel Stratix 10 FPGA IP Error Code Responses and Description to update the description for UNKNOWN_BR.
· Updated the Writing Command Packet and Reading Command Packet sections in the Using the Mailbox Client Intel Stratix 10 FPGA IP Core topic.
· Updated the Mailbox Client Intel Stratix 10 FPGA IP Core Use Case Examples topic. · Removed the following topics:
-- Example 1: Reading Intel eASICTM N5X IDCODE and Voltage -- Example 2: Read and Write EPCQ-L or QSPI Devices
· Updated Table: Command List and Description to include the following commands: -- Updated the descriptions for GET_TEMPERATURE. -- Added new commands: · RSU_IMAGE_UPDATE · CONFIG_STATUS · RSU_STATUS -- Removed the command GET_DESIGNHASH.
· Updated Table: Error Code Responses and Description to update the value of the following error code responses: -- NOT_CONFIGURED -- ALT_SDM_MBOX_RESP_DEVICE_BUSY -- ALT_SDM_MBOX_RESP_NO_VALID_RESP_AVAILABLE -- ALT_SDM_MBOX_RESP_ERROR
· Added a note to Figure: Mailbox Client Intel Stratix 10 FPGA IP Core Block Diagram. · Made minor editorial updates.
Initial release.

Send Feedback

Mailbox Client Intel® FPGA IP User Guide 41

UG-20087 | 2021.11.10 Send Feedback

2. Appendix: CONFIG_STATUS and RSU_STATUS Error Code Descriptions
The CONFIG_STATUS and RSU_STATUS commands allows you to check the current configuration status or the current remote system upgrade status. The commands return 0 when there is no error. If the operation was unsuccessful, the command returns at least one error code described in the table below.
The Error Code field in the command header provides details of major and minor error codes. For more information about specific bits representing the major and minor error codes in the CONFIG_STATUS and RSU_STATUS command, refer to the Command List and Description table.

Figure 6.

Command Header Format

31 30 29 28 27 26 25 24 23 22 21 20 19 18 17 16 15 14 13 12 11 10 9 8 7 6 5 4 3 2 1 0

Reserved

Length

Command/Error Code

Table 23.

CONFIG_STATUS and RSU_STATUS Major Error Code Descriptions
Table displays the major error codes and their descriptions received through the Error Code field.

Major Error Code

Error Type

Description

0xF001

ERR_BITSTREAM_ERROR

Indicates a bitstream error.

0xF002

ERR_EXT_HW_ACCESS_FAIL Indicates an external hardware access error.

0xF003

ERR_BITSTREAM_ CORRUPTION

Indicates a bitstream corruption error.

0xF004

ERR_INTERNAL_ERROR

Indicates an internal error due to misunderstood bitstream element.

0xF005

ERR_DEVICE_ERROR

Indicates a device operation error.

0xF006

ERR_HPS_WDT

Indicates the HPS watchdog timeout failure. Ensure that your design resets the watchdog timer correctly.

0xF007

ERR_INTERNAL_UNKNOWN_ ERROR

Indicates an internal device error due to an unknown task.

0xF008

ERR_SYSTEM_INIT_ERROR Indicates an error due to the system initialization failure.

0xF009

ERR_DECRYPTION_ERROR

Indicates an error due to a bitstream decryption.

ISO 9001:2015 Registered

2. Appendix: CONFIG_STATUS and RSU_STATUS Error Code Descriptions UG-20087 | 2021.11.10

Table 24.

CONFIG_STATUS and RSU_STATUS Minor Error Code Descriptions
Table displays the minor error codes and their descriptions received through the Error Code field.

Minor Error Code

Description

0x0001

Indicates an error during configuration.
Refer to the Configuration User Guide for details on the debug guidelines. Check the latest Intel Quartus Prime software release for possible fixes.

0x0002

Indicates a QSPI-related error due to the following conditions: · An incorrect connection between the QSPI device and the FPGA device. · QSPI device is in reset mode.

0x0003

Indicates a configuration error due to a corrupted bitstream. Ensure a valid connection between the device and the configuration source.

0x0004

Indicates a configuration error due to an incompatible bitstream with the device. Ensure the usage of a correct bitstream.

0x0005 - 0x0007

Indicates a configuration error due to a corrupted bitstream. Ensure a valid connection between the device and the configuration source.

0x0008 0x0009 - 0x0014

Indicates an error during configuration.
Refer to the Configuration User Guide for details on the debug guidelines. Check the latest Intel Quartus Prime software release for possible fixes.

0x0015

Indicates a bitstream authentication error during configuration. Ensure you signed the bitstream with the correct signing key.

0x0016

Indicates a configuration error due to a corrupted bitstream. Ensure a valid connection between the device and the configuration source.

0x0017 - 0x0024

Indicates an error during configuration.
Refer to the Configuration User Guide for details on the debug guidelines. Check the latest Intel Quartus Prime software release for possible fixes.

0x0025

Indicates a firmware transitional error during configuration. Ensure the device firmware and the current Intel Quartus Prime software version are compatible.
To recover, remove the current running firmware from the device.

0x0026 - 0x0031

Indicates an error during configuration.
Refer to the Configuration User Guide for details on the debug guidelines. Check the latest Intel Quartus Prime software release for possible fixes.

0x0032

Indicates a PMBUS error during configuration due to an incorrect VID setting in the Intel Quartus Prime project.
The target device failed to communicate with a smart regulator or PMBUS master on a board.

0x0033

0x0034 - 0x0035

Indicates an error during configuration.
Refer to the Configuration User Guide for details on the debug guidelines. Check the latest Intel Quartus Prime software release for possible fixes.

0x0036

Reserved

0x0037 - 0x0041

Indicates a configuration error due to a corrupted bitstream. Ensure a valid connection between the device and the configuration source.

0x0042

Indicates an incompatible partial reconfiguration (PR) bitstream. Ensure you use the PR bitstream compatible with the current base design.

0x0043 - 0x0049

Reserved

0x004A- 0x004F

Indicates an error during configuration. Refer to the Configuration User Guide for details on the debug guidelines. Check the latest Intel Quartus Prime software release for possible fixes.
continued...

Send Feedback

Mailbox Client Intel® FPGA IP User Guide 43

2. Appendix: CONFIG_STATUS and RSU_STATUS Error Code Descriptions UG-20087 | 2021.11.10

Minor Error Code 0x0050
0x0051 - 0x0052 0x0053 - 0x0054
0x0055 0x0056 - 0x0058 0x0059 - 0x0061
0x0062 0x0063 0x0064 - 0x0066 0x0067
0x0068 0x0069 0x006A - 0x0075 0xC001 0xC002 - 0xC006 0xC007 0xC008 0xC009 0xC00A 0xC00B

Description
Indicates an error during configuration due to a device mismatch between the Intel Quartus Prime project and the target device.
Indicates a configuration error due to a corrupted bitstream. Ensure a valid connection between the device and the configuration source.
Indicates a bitstream decryption error due to a corrupted bitstream. Ensure a valid connection between the device and the configuration source.
Indicates an error during configuration. Refer to the Configuration User Guide for details on the debug guidelines. Check the latest Intel Quartus Prime software release for possible fixes.
Indicates a configuration error due to a corrupted bitstream. Ensure a valid connection between the device and the configuration source.
Indicates an error during configuration. Refer to the Configuration User Guide for details on the debug guidelines. Check the latest Intel Quartus Prime software release for possible fixes.
Indicates a configuration error due to a corrupted bitstream. Ensure a valid connection between the device and the configuration source.
Indicates an error during configuration. Refer to the Configuration User Guide for details on the debug guidelines. Check the latest Intel Quartus Prime software release for possible fixes.
Indicates a configuration error due to a corrupted bitstream. Ensure a valid connection between the device and the configuration source.
Indicates an error during configuration. Refer to the Configuration User Guide for details on the debug guidelines. Check the latest Intel Quartus Prime software release for possible fixes.
Indicates that the detected bitstream is incompatible due to the security enabled settings. You cannot use the bitstream from an advanced security-enabled devices on a non-advanced security-enabled device. Ensure the Intel Quartus Prime project device matches the target device.
Indicates that the detected bitstream is invalid due to reached maximum number of supported partial reconfiguration (PR) authentication. The bitstream supports up to 32 PR partitions.
Indicates an error during configuration. Refer to the Configuration User Guide for details on the debug guidelines. Check the latest Intel Quartus Prime software release for possible fixes.
Indicates a firmware error during reconfiguration. Check the latest Intel Quartus Prime software release for possible fixes.
Indicates a bitstream error during reconfiguration. Check the bitstream validity. If corrupted, regenerate and configure bitstream again.
Indicates an error due to transitioning to other firmware version or application image. Ensure the bitstream is valid. If corrupted, regenerate and reprogram QSPI flash with RSU image via the JTAG interface.
Indicates an error during configuration. Refer to the Configuration User Guide for details on the debug guidelines. Check the latest Intel Quartus Prime software release for possible fixes.
Indicates a bitstream authentication error during reconfiguration. Ensure you use the correct signing key when signing the bitstream.
Indicates an error during configuration. To recover, power cycle the device.
Indicates an error during configuration. Refer to the Configuration User Guide for details on the debug guidelines. Check the latest Intel Quartus Prime software release for possible fixes.
continued...

Mailbox Client Intel® FPGA IP User Guide 44

Send Feedback

2. Appendix: CONFIG_STATUS and RSU_STATUS Error Code Descriptions UG-20087 | 2021.11.10

Minor Error Code 0xC00D 0xC00E 0xC00F 0xD001 0xD002 0xD003 0xD004 0xD005 0xD006 0xD007 0xD008 0xD009 0xD00A 0xD00B 0xD00C 0xD00D 0xD00E 0xD00F 0xD010

Description
Indicates a hardware error during reconfiguration. To recover, power cycle the device.
Indicates a bitstream error during reconfiguration. Check the bitstream validity. If corrupted, regenerate and configure bitstream again.
Indicates an error when accessing the QSPI flash memory. Reconfigure device by toggling nCONFIG pin signal or power cycle the device.
Indicates an authentication failure for the firmware. Ensure you use the correct firmware signing key when enabling firmware co-signing feature.
Indicates an authentication failure for the design. Ensure you sign the bitstream with a correct signing key.
Indicates an error when loading the application image from QSPI flash. Ensure the application image located at the correct address in QSPI flash.
Indicates an error when parsing the RSU CPB block. RSU CPB block is corrupted. To recover, toggle the nCONFIG pin to restart the RSU. If the issue persists, reprogram the RSU CPB block data.
Indicates an error during configuration. Refer to the Configuration User Guide for details on the debug guidelines. Check the latest Intel Quartus Prime software release for possible fixes.
Failed to load factory image. Ensure the factory image is valid. If corrupted, regenerate and reprogram the factory image in the flash. When authentication is enabled, ensure you use the correct signing key.
Indicates an error when loading the application image. Check the application image validity. If corrupted, regenerate and reprogram again the application image in the flash.
Indicates an error during factory image update in flash memory. Check the factory update image validity. If corrupted, regenerate and reprogram again the factory updated image in the flash.
Indicates an error during a decision firmware update in flash memory. Check the factory update image validity. If corrupted, regenerate and reprogram again the factory updated image. Ensure you use the correct signing key when authentication is enabled.
Indicates an error during a decision firmware update in flash memory. Flash memory may have reset during the update process. To recover, toggle the nCONFIG signal to restart the update process.
Indicates an error during a decision firmware update in flash memory. Flash memory may have reset during the update process. To recover, toggle the nCONFIG signal to restart the update process.
Indicates an error during RSU CPB table update in flash. RSU CPB block data may be corrupted. To recover, regenerate the RSU image containing the updated factory image and program it to flash.
Indicates an error during combined application image update in flash memory. Check the combined application image validity. If corrupted, regenerate and reprogram again the combined application update image in the flash.
Indicates an error during a decision firmware update in flash memory. Flash memory may have reset during the update process. To recover, toggle the nCONFIG signal to restart the update process.
Indicates an error when parsing the DCIO section. The DCIO section may be corrupted. To recover, regenerate the RSU image containing new decision firmware or DCIO section and program it to flash.
Indicates an error in the RSU CPB0 table. The CPB0 table may be corrupted. To recover the CPB0, regenerate the RSU image containing new decision firmware and program it to flash.
continued...

Send Feedback

Mailbox Client Intel® FPGA IP User Guide 45

2. Appendix: CONFIG_STATUS and RSU_STATUS Error Code Descriptions UG-20087 | 2021.11.10

Minor Error Code 0xD011 0xD012 0xD013 0xE001
0xE002 0xE003 - 0xE008 0xE009 - 0xE00B
0xE00C

Description
Indicates an error in the RSU CPB0 and CPB1 tables. Both CPB0 and CPB1 table entries may be corrupted. To recover CPB0 and CPB1, regenerate the RSU image containing new decision firmware and program it to flash.
Indicates a successful non-JTAG device provisioning. The successful decision firmware loads the highest priority application image.
Indicates an error during the device provisioning.
Indicates an error during configuration. Refer to the Configuration User Guide for details on the debug guidelines. Check the latest Intel Quartus Prime software release for possible fixes.
Indicates an error during configuration. Refer to the Configuration User Guide for details on the debug guidelines. Check the latest Intel Quartus Prime software release for possible fixes.
Reserved
Indicates an error during configuration. Refer to the Configuration User Guide for details on the debug guidelines. Check the latest Intel Quartus Prime software release for possible fixes.
Reserved

Related Information · Intel Stratix 10 Configuration User Guide: Debugging Guide · Intel Agilex Configuration User Guide: Debugging Guide

Mailbox Client Intel® FPGA IP User Guide 46

Send Feedback

References

Antenna House PDF Output Library 6.6.1359 (Linux64)