Mailbox Client Intel® FPGA IPs User Guide

Download PDF
ID 683290
Date 7/08/2024
Public

A newer version of this document is available. Customers should click here to go to the newest version.

Document Table of Contents
Document Table of Contents x
1. Mailbox Client Intel FPGA IP User Guide 2. Appendix: CONFIG_STATUS and RSU_STATUS Error Code Descriptions
1. Mailbox Client Intel FPGA IP User Guide x
1.1. Release Information 1.2. Device Family Support 1.3. Parameters 1.4. Mailbox Client Intel® FPGA IP Core Interface Signals 1.5. Mailbox Client Intel FPGA IP Avalon® Memory-Mapped Interface 1.6. Commands and Responses 1.7. Specifying the Command and Response FIFO Depths 1.8. Enabling Cryptographic Services 1.9. Using the Mailbox Client Intel® FPGA IP 1.10. Accessing Quad SPI Flash Mailbox Client Intel FPGA IP Core Use Case Examples 1.11. Nios® II and Nios® V Processors HAL Driver 1.12. Mailbox Client Intel FPGA IP User Guide Archives 1.13. Document Revision History for the Mailbox Client Intel® FPGA IP User Guide
1.4. Mailbox Client Intel® FPGA IP Core Interface Signals x
1.4.1. Clock and Reset Interfaces 1.4.2. Avalon® Memory-Mapped Interface 1.4.3. AXI Manager Interface
1.5. Mailbox Client Intel FPGA IP Avalon® Memory-Mapped Interface x
1.5.1. Interrupt Enable Register 1.5.2. Interrupt Status Register 1.5.3. Timer Registers
1.6. Commands and Responses x
1.6.1. Operation Commands 1.6.2. Error Code Responses 1.6.3. Error Code Recovery
1.11. Nios® II and Nios® V Processors HAL Driver x
1.11.1. Mailbox Client HAL API 1.11.2. LibRSU HAL API
1.11.1. Mailbox Client HAL API x
1.11.1.1. Mailbox Client Driver API
1.11.2. LibRSU HAL API x
1.11.2.1. Configuration Parameter 1.11.2.2. Error Codes 1.11.2.3. Using LibRSU HAL API without Valid SPT or CPB 1.11.2.4. Data Type 1.11.2.5. Functions 1.11.2.6. RSU Client API
1. Mailbox Client Intel FPGA IP User Guide
2. Appendix: CONFIG_STATUS and RSU_STATUS Error Code Descriptions

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

Document Version Quartus® Prime Version Changes
2024.07.08 24.2
  • Updated the Command List and Description table in the Operation Commands section with the following changes.
    • Added GET_I2C_TELEMETRY.
    • Updated description for CONFIG_STATUS.
2024.04.01 24.1
  • Added Agilex 5 Mailbox Client Intel® FPGA IP.
  • Added support for Agilex™ 5 devices.
  • Added the Release Information section.
  • Added link to a KDB in the Mailbox Client Driver API section.
  • Added the following commands to the Command List and Description table in the Operation Commands section.
    • READ_SEU_STATS
    • INSERT_SAFE_SEU_ERROR
    • INSERT_ECC_ERROR
Document Version Quartus® Prime Version IP Version Changes
2023.12.04 23.4 21.0.0 Added additional Minor Error Code in CONFIG_STATUS and RSU_STATUS Minor Error Code Descriptions table in Appendix: CONFIG_STATUS and RSU_STATUS Error Code Descriptions section.
2023.10.02 23.3 21.0.0 Added the following to the Command List and Description table in the Operation Commands section.
  • READ_SEU_ERROR
  • STATUS_VR
2023.08.01 23.2 21.0.0
  • Updated the description for the QSPI_OPEN and QSPI_SET_CS commands in the Command List and Description table in section Operation Commands.
  • Updated the error code recovery for value C in the Error Code Recovery for Known Error Codes table in the Error Code Recovery section.
  • Added row for QSPI_READ_SHA512 command in the Command List and Descriptiontable in section Operation Commands.
  • Updated the Mailbox Client Intel® FPGA IP Interfaces figure in the Mailbox Client Intel® FPGA IP Core Interface Signals section to include avmm_waitrequest.
  • Updated the Avalon® Memory-Mapped Interface table in the Avalon® Memory-Mapped Interface section to include avmm_waitrequest.
  • Updated the mailbox_client_flash _erase_blocktable in the Mailbox Client Driver API section to replace Kbytes with KB.
Document Version Quartus® Prime Version Changes
2023.04.10 22.4
  • Added link to a KDB in the Mailbox Client with Avalon® Streaming Interface Intel FPGA IP Overview section.
  • Updated content in the LibRSU HAL API section to better clarify how to obtain ZLIB.
  • Updated product family name to " Intel Agilex® 7".
  • Renamed Avalon ST and Avalon MM to Avalon streaming interface and Avalon memory-mapped interface.
2022.12.19 22.4
  • Added GET_CONFIGURATION_TIME and QSPI_READ_SHA command in the Command List and Description table.
  • Updated default value and description for rsu_protected_slot in the Configuration Parameter table.
2022.09.26 22.3
  • Updated the GET_VOLTAGE command row in the Command List and Description table.
  • Revised Using the Mailbox Client Intel FPGA IP. Removed the "Wait 10 ms between back to back commands to the SDM mailbox" in Restrictions.
  • Added a note to Table: Device Family Support.
  • Revised the description for LENGTH header in Table: Command and Response Header Description.
  • Revised note about enabled bits in Interrupt Enable Register.
  • Added reference to Intel® Agilex™ Device Security User Guide in Enabling Cryptographic Services.
  • Revised QSPI_SET_CS command description in the Command List and Description table.
  • Edited the title for Nios II HAL Driver to Nios II and Nios V Processors Hal Driver
    • Added text to specify the use of Quartus® Prime Pro Edition software version prior 21.4.
  • Added the following topics:
    • Mailbox Client HAL API
    • LibRSU HAL API
    • Configuration Parameter
    • Error Codes
    • Using LibRSU HAL API without Valid SPT or CPB
    • Data Type
    • Functions
    • RSU Client API
2022.04.04 22.1
  • Updated instances of AXI target to AXI manager.
  • Updated crypto service-specific parameter name from HAS_OFFLOAD to Enable Crypto Service.
  • Added bit 8 and bit 9 in the following tables:
    • Interrupt Enable Register
    • Interrupt Status Register
  • Updated the Command List and Description table.
    • Updated pin status description for the CONFIG_STATUS command.
    • Removed the REBOOT_HPS command.
2021.11.10 21.3 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.
2021.06.21 21.2 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.
2021.03.29 21.1 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.
2020.12.14 20.4 Made the following 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 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.
2020.10.05 20.3 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
2020.06.30 20.2 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.
2020.04.13 20.1 Made the following 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.
2020.03.17 19.3 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.
2019.09.30 19.3 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 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 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.
  • 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 Changes
2019.04.19
  • 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.
2019.03.14
  • 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.
2019.02.25
  • 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 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.
  • Updated Table: Mailbox Client 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 eASIC™ N5X IDCODE and Voltage
    • Example 2: Read and Write EPCQ-L or QSPI Devices
2018.10.15
  • 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.
2018.02.14 Initial release.
Level Two Title