Mailbox Client Intel FPGA IP User Guide
Version Information
Updated for: |
---|
Intel® Quartus® Prime Design Suite 20.4 |
IP Version 20.0.0 |
1. Mailbox Client Intel FPGA IP User Guide
The Mailbox Client Intel FPGA IP is a bridge between a host and the Intel® Stratix® 10 secure device manager (SDM). 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.
- 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)
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.
- 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.
1.1. Device Family Support
- 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.
Device Family | Support |
---|---|
Intel® Stratix® 10 | Final |
Intel® Agilex™ | Advance |
1.2. Commands and Responses
The first word of the command and response packets is a header that provides basic information about the command or response.
The following table describes the fields of the header command.
Header | Bit | Description |
---|---|---|
Reserved | [31:28] | Reserved. |
ID | [27:24] | The command ID. The response header returns the ID specified in the command header. Refer to Operation Commands for command descriptions. |
0 | [23] | Reserved. |
LENGTH | [22:12] | 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 | [11] | Reserved. Must be set to 0. |
Command Code/Error Code | [10: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.2.1. Operation Commands
Resetting Quad SPI Flash
Command | Code (Hex) | Command Length 1 | Response Length 1 | Description | |||
---|---|---|---|---|---|---|---|
NOOP | 0 | 0 | 0 | Sends an OK status response. | |||
GET_IDCODE | 10 | 0 | 1 | The response contains one argument which is the JTAG IDCODE for the device | |||
GET_CHIPID | 12 | 0 | 2 | The response contains 64-bit CHIPID value with the least significant word first. | |||
GET_USERCODE | 13 | 0 | 1 | The response contains one argument which is the 32-bit JTAG USERCODE that the configuration bitstream writes to the device. | |||
GET_VOLTAGE | 18 | 1 | 1 | 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.2 3 |
|||
GET_TEMPERATURE | 19 | 1 | n 4 |
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:
For
Intel®
Agilex™
devices, use the
sensor_req argument to specify the locations.
The sensor_req includes the following fields:
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. |
|||
RSU_IMAGE_UPDATE | 5C | 2 | 0 |
Triggers reconfiguration from the data source which 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. If you do not provide this argument its value is assumed to be 0.
Once the device processes this command and proceeds to reconfigure the device, the link between the external host and FPGA is lost. The device/FPGA doesn't return a response to the Mailbox Client. Important: When resetting quad SPI, you must follow
instructions specified in Resetting Quad SPI Flash.
|
|||
RSU_GET_SPT | 5A | 0 | 4 |
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: |
|||
Offset | Name | Description | |||||
0 | SPT0[63:32] | SPT0 address in quad SPI flash. | |||||
1 | SPT0[31:0] | ||||||
2 | SPT1[63:32] | SPT1 address in quad SPI flash. | |||||
3 | SPT1[31:0] | ||||||
CONFIG_STATUS | 4 | 0 | 6 |
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 | |||||
0 | State | Describes the most recent
configuration related error. Returns 0 when there are no configuration errors. The error field has 2 fields:
|
|||||
1 | Version | The version of the RSU data structure. | |||||
2 | Pin status |
|
|||||
3 | Soft function status | Contains the value of each
of the soft functions, even if you have not assigned the function to an SDM pin.
|
|||||
4 | Error location | Contains the error location. Returns 0 if there are no errors. | |||||
5 | Error details | Contains the error details. Returns 0 if there are no errors. | |||||
RSU_STATUS | 5B | 0 | 9 | 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.
|
|||||
4 | State | Failure code of the failing
image. The error field has two parts:
Returns 0 for no failures. Refer to the Table 4 and Table 5 for more information. |
|||||
5 | Version |
The version of the RSU software. |
|||||
6 | Error location | Stores the error location of the failing image. Returns 0 for no errors. | |||||
7 | Error details | Stores the error details for the failing image. Returns 0 if there are no errors. | |||||
8 | Current image retry counter |
Count of the number of retries that 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. |
|||||
RSU_NOTIFY | 5D | 1 | 0 |
Clears all error information in the RSU_STATUS response and resets the retry counter. The one-word
argument has the following fields:
|
|||
QSPI_OPEN | 32 | 0 | 0 |
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. Note: 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.
Important: When resetting quad SPI, you must follow
instructions specified in Resetting Quad SPI Flash.
|
|||
QSPI_CLOSE | 33 | 0 | 0 | Closes the exclusive access to
the quad SPI
interface. Important: When resetting quad SPI, you must follow
instructions specified in Resetting Quad SPI Flash.
|
|||
QSPI_SET_CS | 34 | 1 | 0 | Specifies one of the attached
quad SPI devices via the chip select lines. Takes a one-word argument as described
below:
This command is optional for the AS x4 configuration scheme. Is required for all other configuration schemes. 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® 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.
|
|||
QSPI_READ | 3A | 2 | N |
Reads the attached quad SPI device. The maximum transfer size is 4 kilobytes (KB) or 1024 words. Takes two arguments:
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.
|
|||
QSPI_WRITE | 39 | 2+N | 0 |
Writes data to the quad SPI device. The maximum transfer size is 4 kilobytes (KB) or 1024 words. Takes three arguments:
To prepare memory for writes, Intel recommends using 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.
|
|||
QSPI_ERASE | 38 | 2 | 0 | Erases a sector of the quad
SPI device. Takes two arguments:
Important: When resetting quad SPI, you must follow
instructions specified in Resetting Quad SPI Flash.
|
|||
QSPI_READ_DEVICE_REG | 35 | 2 | N | Reads registers from the quad
SPI device. The maximum read is 8 bytes. Takes two arguments.
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.
|
|||
QSPI_WRITE_DEVICE_REG | 36 | 2+N | 0 | Writes to registers of the
quad SPI. The maximum write is 8 bytes. Takes three arguments:
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.
|
|||
QSPI_SEND_DEVICE_OP | 37 | 1 | 0 | Sends a command opcode to the
quad SPI. Takes one argument:
A successful command returns the OK response code. Important: When resetting quad SPI, you must follow
instructions specified in Resetting Quad SPI Flash.
|
|||
REBOOT_HPS | 47 | 0 | 0 | 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. |
Major Error Code | Error Type | Description |
---|---|---|
0xF001 | BITSTREAM_ERROR | Potential unsigned bitstream used. Ensure the bitstream is signed with the correct key. |
0xF002 | HARDWARE_ACCESS_FAILURE | Failure to communicate to PMBus-compliant voltage regulator. Check your power management and smart voltage identification (SmartVID) parameter settings and PMBus interface connections. |
0xF003 | BITSTREAM_CORRUPTION | Bitstream is corrupt. Ensure the bit stream in configuration device or flash is not corrupt. |
0xF004 | INTERNAL_ERROR |
This major code may indicate the following error events:
|
0xF005 | DEVICE_ERROR |
Indicates an SDM internal device error. The following errors
are possible:
Contact your local Field Applications Engineer (FAE). Alternatively, submit a Service Request on the My Intel support page to get the support on capturing the error log for further debug. |
0xF006 | HPS_WATCHDOG_TIMEOUT | HPS watchdog timeout failure. Ensure that your design resets the watchdog timer correctly. |
0xF007 | INTERNAL_UNKNOWN_ERROR |
Indicates an internal device error due to an unknown task.
You can contact your local Field Applications Engineer (FAE). Alternatively, submit a Service Request on the My Intel support page to get the support on capturing the error log for further debug. |
Minor Error Code | Error Type | Description |
---|---|---|
0xD001 | RSU_CMF_AUTH_ERR | Authentication failure for the firmware. |
0xD002 | RSU_USER_AUTH_ERR | Authentication failure for the design. |
0xD003 | RSU_CMF_DESC_SHA_MISMATCH | The SHA does not match for the firmware descriptor. |
0xD004 | RSU_POINTERS_NOT_FOUND_ERR | Unable to read data from boot ROM on first boot after the device exits power-on reset (POR). |
0xD005 | RSU_QSPI_REQ_CHANGE | Unable to configure the quad SPI flash during RSU initialization. |
0xD006 | RSU_FACTORY_IMAGE_FAILED | Failed to load any image, including the factory image. |
0xD007 | RSU_CMF_TYPE_ERR | The firmware version does not match the version that was previously loaded. |
1.2.2. Error Code Responses
Value (Hex) | Error Code Response | Description | |||
---|---|---|---|---|---|
0 | OK |
Indicates that the command completed successfully. A command may erroneously return the OK status if a command, such as QSPI_READ is partially successful. |
|||
1 | INVALID_COMMAND | Indicates that the currently loaded boot ROM cannot decode or recognize the command code. | |||
3 | UNKNOWN_COMMAND | Indicates that the currently loaded firmware cannot decode the command code. | |||
4 | INVALID_COMMAND_PARAMETERS | Indicates that the command is incorrectly formatted. For example, the length field setting in header is not valid. | |||
6 | COMMAND_INVALID_ON_SOURCE | Indicates that the command is from a source for which it is not enabled. | |||
8 | CLIENT_ID_NO_MATCH | 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. | |||
9 | INVALID_ADDRESS | The address is invalid. This error
indicates one of the following conditions:
|
|||
A | AUTHENTICATION_FAIL | Indicates the configuration bitstream signature authentication failure. | |||
B | TIMEOUT | This
error indicates time out due to the following conditions:
|
|||
C | HW_NOT_READY | Indicates
one of the following conditions:
|
|||
D | HW_ERROR | Indicates that the command completed unsuccessfully due to unrecoverable hardware error. | |||
80 - 8F | COMMAND_SPECIFIC_ERROR | Indicates a command specific error due to an SDM command you used. | |||
SDM Command | Error Name | Error code | Description | ||
GET_CHIPID | EFUSE_SYSTEM_FAILURE | 0x82 | Indicates that the eFuse cache pointer is invalid. | ||
QSPI_OPEN/ QSPI_CLOSE/ QSPI_SET_CS/ QSPI_READ_DEVICE_REG/ QSPI_WRITE_DEVICE_REG/ QSPI_SEND_DEVICE_OP/ QSPI_READ |
QSPI_HW_ERROR | 0x80 | Indicates QSPI flash memory error. This error
indicates one of the following conditions:
|
||
QSPI_ALREADY_OPEN | 0x81 | Indicates that the client's exclusive access to QSPI flash via QSPI_OPEN command is already open. | |||
100 | NOT_CONFIGURED | Indicates that the device is not configured. | |||
1FF | ALT_SDM_MBOX_RESP_DEVICE_ BUSY | Indicates that the device is
busy
due to following
use
cases:
|
|||
2FF | ALT_SDM_MBOX_RESP_NO_VALID_RESP_AVAILABLE | Indicates that there is no valid response available. | |||
3FF | ALT_SDM_MBOX_RESP_ERROR | General Error. |
1.2.3. Error Code Recovery
Value | Error Code Response | Error Code Recovery |
---|---|---|
4 | INVALID_COMMAND_PARAMETERS | 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. |
6 | COMMAND_INVALID_ON_SOURCE | Resend the command from valid source such as JTAG, HPS, or core fabric. |
8 | CLIENT_ID_NO_MATCH | Wait for the client who opened the access to quad SPI to complete its access and then closes the exclusive access to quad SPI. |
9 | INVALID_ADDRESS |
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:
For RSU: Send command with a valid start address of the factory image or application. |
B | TIMEOUT |
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. |
C | HW_NOT_READY |
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. |
80 | QSPI_HW_ERROR | Check the QSPI interface signal integrity and to ensure the QSPI device is not damaged. |
81 | QSPI_ALREADY_OPEN | Client already opened QSPI. Continue with the next operation. |
82 | EFUSE_SYSTEM_FAILURE | Attempt reconfiguration or power cycle. If error persists after reconfiguration or power cycle, the device may be damaged and unrecoverable. |
100 | NOT_CONFIGURED | Send a bitstream that configures the HPS. |
1FF | ALT_SDM_MBOX_RESP_DEVICE_ BUSY |
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.3. Mailbox Client Intel FPGA Core Signals
The host communicates with the Mailbox Client Intel FPGA over its Avalon® Memory-Mapped ( Avalon® MM) 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.
Signal Role | Width | Direction | Description |
---|---|---|---|
Avalon® -MM Interface Signals | |||
avmm_address | 4 | Input | Avalon® MM address. |
avmm_write | 1 | Input | Avalon® MM write request. |
avmm_read | 1 | Input | Avalon® MM read request. |
avmm_writedata | 32 | Input | Avalon® MM writedata bus. |
avmm_readdata | 32 | Output | Avalon® MM readdata bus. |
avmm_readdatavalid | 1 | Output | Avalon® MM readdata valid. |
Clock and Reset | |||
clk | 1 | Input | Input clock to clock the IP. The maximum frequency is 250 MHz. |
reset | 1 | Input | 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 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.
|
irq | 1 | Output | Interrupt signal. Drives the value of the AND of the interrupt status and interrupt enable registers. |
1.4. Mailbox Client Intel FPGA IP Avalon MM Memory Map
Offset (word) | R/W | 31 | 30:2 | 1 | 0 |
---|---|---|---|---|---|
Base address + 0 | W | Command | |||
Base address + 1 | W | Command last word (eop) | |||
Base address + 2 | R | Command FIFO empty space | |||
Base address + 3 | N/A | Reserved | |||
Base address + 4 | N/A | Reserved | |||
Base address + 5 | R | Response data | |||
Base address + 6 | R | Response FIFO fill level | EOP | SOP | |
Base address + 7 | R/W | Interrupt enable register (IER) | |||
Base address + 8 | R | 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
Bit | Fields | Access | Default Value | Description |
---|---|---|---|---|
31:6 | Reserved | |||
5 | EN_BACKPRESSURE_TIMEOUT | R/W | 0x0 | The enable interrupt bit for SDM backpressure
timeout.
|
4 | EN_EOP_TIMEOUT | R/W | 0x0 | The enable interrupt bit for EN_EOP_TIMEOUT.
|
3 | EN_COMMAND_INVALID | R/W | 0x0 | The
enable interrupt bit for COMMAND_INVALID.
|
2 | Reserved | — | — | Reserved. |
1 | EN_CMD_FIFO_NOT_FULL | R/W | 0x0 | The enable for the command FIFO full
interrupt.
|
0 | EN_DATA_VALID | R/W | 0x0 | The enable for the data valid interrupt.
|
1.4.2. Interrupt Status Register
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.
Bit | Fields | Access | Default Value | Description |
---|---|---|---|---|
31:6 | Reserved | |||
5 | BACKPRESSURE_TIMEOUT | R | 0x0 | SDM backpressure timer interrupt.
|
4 | EOP_TIMEOUT | R | 0x0 |
End of Packet (EOP) timer interrupt.
Indicates that the Mailbox Client IP did not
receive the full command with EOP due to:
|
3 | COMMAND_INVALID | R | 0x0 | 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.
|
2 | Reserved | — | — | Reserved. |
1 | CMD_FIFO_NOT_FULL | R | 0x0 | Command FIFO is not full interrupt.
The FIFO automatically clears this bit. You do not need to clear this bit manually. |
0 | DATA_VALID | R | 0x0 | Data valid interrupt.
The FIFO automatically clears this bit. You do not need to clear this bit manually. |
1.4.3. Timer Registers
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 need to reset the Mailbox Client IP.
Bit | Fields | Access | Default Value 5 | Description |
---|---|---|---|---|
31 | Timer 1 enable | R/W | 0x0 |
Timer 1
period
enable
bit.
The bit is enabled once.
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 need to re-enable it again. |
30:0 | Timer 1 period | R/W | 0x7FF_FFFF |
When enabled, it 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
Bit | Fields | Access | Default Value 6 | Description |
---|---|---|---|---|
31 | Timer 2 enable | R/W | 0x0 |
Timer 2
period
enable bit. The bits is enabled
once.
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 need to re-enable it again. |
30:0 | Timer 2 period | R/W | 0x7FF_FFFF | When enabled, it 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. |
Resetting the Mailbox Client IP resets the timer 2 register to the default value.
1.5. Specifying the Command and Response FIFO Depths
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.6. Using the Mailbox Client Intel FPGA IP
Writing Command Packet
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 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.
- 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. 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
Reading Response Packet
Read Command Description
- 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.
- Read (base address + 6) to check the SOP (start of packet), EOP (end of packet),
and the Response FIFO fill
level
(n).
To read multiple words complete the following steps:
- If SOP = 1 and EOP = 0, the response has multiple words.
- If the Response FIFO fill level (n) is non-zero, the FIFO has valid data.
- 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:- If SOP = 1 and EOP = 1, the response has a single word.
- If the Response FIFO fill level is non-zero, the FIFO has valid data.
- 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.
- 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 6 for more information.
- 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) is 0 and the EOP is 1. 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
- 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.
- 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:
- Voltage Sensor Intel® FPGA IP
- Chip ID Intel® FPGA IP
- Serial Flash Mailbox Client Intel® FPGA IP
- Temperature Sensor Intel® FPGA IP
1.7. 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.
- QSPI OPEN
- QSPI_SET_CS
- 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
- QSPI_CLOSE
1.8. 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 | IP Core Version | User Guide |
---|---|---|
20.3 | 20.0.0 | Mailbox Client Intel FPGA IP User Guide |
20.2 | 20.0.0 | Mailbox Client Intel FPGA IP User Guide |
20.1 | 20.0.0 | Mailbox Client Intel FPGA IP User Guide |
19.3 | 19.1 | Mailbox Client Intel FPGA IP User Guide |
18.1 | 18.1 | Mailbox Client Intel FPGA IP User Guide |
17.1 | 17.1 | Mailbox Client Intel FPGA IP User Guide |
1.9. Document Revision History for the Mailbox Client Intel FPGA IP User Guide
Document Version | Intel® Quartus® Prime Version | Changes |
---|---|---|
2020.12.14 | 20.4 | Made the following changes:
|
2020.10.05 | 20.3 | Made the following changes:
|
2020.06.30 | 20.2 | Made the following changes:
|
2020.04.13 | 20.1 | Made the following changes:
|
2020.03.17 | 19.3 | Made the following changes:
|
2019.09.30 | 19.3 | Made the following changes:
|
Document Version | Changes |
---|---|
2019.04.19 |
|
2019.03.14 |
|
2019.02.25 |
|
2018.10.15 |
|
2018.02.14 | Initial release. |