Intel Agilex® 7 Hard Processor System Remote System Update User Guide

Download PDF
ID 683184
Date 6/09/2023
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. Overview 2. Use Cases 3. Quad SPI Flash Layout 4. Intel® Quartus® Prime Software and Tool Support 5. Software Support 6. Flash Corruption - Detection and Recovery 7. Remote System Update Example 8. Version Compatibility Considerations 9. Intel Agilex® 7 Hard Processor System Remote System Update User Guide Archives 10. Document Revision History for the Intel Agilex® 7 Hard Processor System Remote System Update User Guide A. Configuration Flow Diagrams B. RSU Status and Error Codes C. U-Boot RSU Reference Information D. LIBRSU Reference Information E. Combined Application Images
1. Overview x
1.1. Features 1.2. System Components 1.3. Glossary
2. Use Cases x
2.1. Manufacturing 2.2. Application Image Boot 2.3. Factory Image Boot 2.4. Modifying the List of Application Images 2.5. Querying RSU Status 2.6. Loading a Specific Image 2.7. Protected Access to Flash 2.8. Remote System Update Watchdog 2.9. RSU Notify 2.10. Updating the Factory Image 2.11. Updating the Decision Firmware 2.12. Retrying when Configuration Fails 2.13. Querying the Decision Firmware Version
3. Quad SPI Flash Layout x
3.1. High Level Flash Layout 3.2. Detailed Quad SPI Flash Layout 3.3. Decision Firmware Data Max Retry Information 3.4. Firmware Version Information
3.1. High Level Flash Layout x
3.1.1. Standard (non-RSU) Image Layout in Flash 3.1.2. RSU Image Layout in Flash – SDM Perspective 3.1.3. RSU Image Layout – Your Perspective
3.2. Detailed Quad SPI Flash Layout x
3.2.1. RSU Image Sub-Partitions Layout 3.2.2. Sub-Partition Table Layout 3.2.3. Configuration Pointer Block Layout 3.2.4. Image Layout
3.2.4. Image Layout x
3.2.4.1. Absolute Application Image Layout
4. Intel® Quartus® Prime Software and Tool Support x
4.1. Intel® Quartus® Prime Pro Edition Software 4.2. Programming File Generator 4.3. Intel® Quartus® Prime Programmer 4.4. Supported QSPI Flash Devices
4.1. Intel® Quartus® Prime Pro Edition Software x
4.1.1. Selecting Factory Load Pin 4.1.2. Enabling HPS Watchdog to Trigger RSU 4.1.3. Setting the Max Retry Parameter
4.2. Programming File Generator x
4.2.1. Programming File Generator File Types 4.2.2. Bitswap Option 4.2.3. Creating Images
4.2.3. Creating Images x
4.2.3.1. Creating Initial Flash Image 4.2.3.2. Creating Application Images 4.2.3.3. Creating Factory Update Images 4.2.3.4. Creating Decision Firmware Update Images 4.2.3.5. Creating Combined Application Images
4.2.3.1. Creating Initial Flash Image x
4.2.3.1.1. Creating Initial Flash Image for FPGA First 4.2.3.1.2. Creating Initial Flash Image for HPS First
5. Software Support x
5.1. SDM RSU Support 5.2. Arm Trusted Firmware Support 5.3. U-Boot RSU Support 5.4. Linux* RSU Support
5.3. U-Boot RSU Support x
5.3.1. U-Boot RSU APIs 5.3.2. U-Boot RSU Commands
5.4. Linux* RSU Support x
5.4.1. Intel® Service Driver 5.4.2. Intel® RSU Driver 5.4.3. LIBRSU Library 5.4.4. RSU Client
6. Flash Corruption - Detection and Recovery x
6.1. Decision Firmware 6.2. Decision Firmware Data 6.3. Configuration Pointer Block 6.4. Sub-Partition Table 6.5. Application Image 6.6. Factory Image 6.7. Example Maintenance Procedure
6.7. Example Maintenance Procedure x
6.7.1. Maintenance Procedure
6.7.1. Maintenance Procedure x
6.7.1.1. Recover Decision Firmware Procedure
7. Remote System Update Example x
7.1. Building RSU Example Binaries 7.2. Flashing the Binaries 7.3. Exercising U-Boot RSU Commands
7.1. Building RSU Example Binaries x
7.1.1. Setting up the Environment 7.1.2. Building the Hardware Projects 7.1.3. Building Arm* Trusted Firmware 7.1.4. Building Linux* 7.1.5. Building U-Boot 7.1.6. Building U-Boot Script 7.1.7. Creating the Initial Flash Image 7.1.8. Creating the Application Image 7.1.9. Creating the Factory Update Image 7.1.10. Creating the Decision Firmware Update Image 7.1.11. Building ZLIB 7.1.12. Building LIBRSU and RSU Client 7.1.13. Building the Root File System 7.1.14. Building the SD Card
7.2. Flashing the Binaries x
7.2.1. Flashing the Initial RSU Image to QSPI 7.2.2. Writing the SD Card Image
7.3. Exercising U-Boot RSU Commands x
7.3.1. Using U-Boot to Perform Basic Operations 7.3.2. Watchdog and Max Retry Operation 7.3.3. Updating the Factory Image Using U-Boot 7.3.4. Fallback on Flash Corruption of Application Images 7.3.5. Additional Flash Corruption Detection and Recovery
7.3.5. Additional Flash Corruption Detection and Recovery x
7.3.5.1. Corrupted Decision Firmware 7.3.5.2. Corrupted Decision Firmware Data 7.3.5.3. Corrupted Configuration Pointer Block 7.3.5.4. Corrupted Sub-Partition Table
8. Version Compatibility Considerations x
8.1. Component Versions 8.2. Component Interfaces 8.3. Component Version Compatibility 8.4. Using Multiple Intel® Quartus® Prime Software Versions for Bitstreams 8.5. Updating U-Boot to Support Different SSBL per Bitstream
8.5. Updating U-Boot to Support Different SSBL per Bitstream x
8.5.1. Using Multiple SSBLs with SD/MMC 8.5.2. Using Multiple SSBLs with QSPI 8.5.3. U-Boot Source Code Details
A. Configuration Flow Diagrams x
A.1. Load Image on Power Up or nConfig Flow A.2. Try Loading Image Process A.3. Request Specific Image Flow A.4. Configure after Image Failure Process A.5. Watchdog Timeout Flow
C. U-Boot RSU Reference Information x
C.1. Configuration Parameters C.2. Error Codes C.3. Using U-Boot RSU Without a Valid SPT or CPB C.4. Macros C.5. Data Types C.6. Functions C.7. RSU U-Boot Commands
C.1. Configuration Parameters x
C.1.1. rsu_protected_slot C.1.2. rsu_log_level C.1.3. rsu_spt_checksum
C.5. Data Types x
C.5.1. rsu_slot_info C.5.2. rsu_status_info
C.6. Functions x
C.6.1. rsu_init C.6.2. rsu_exit C.6.3. rsu_slot_count C.6.4. rsu_slot_by_name C.6.5. rsu_slot_get_info C.6.6. rsu_slot_size C.6.7. rsu_slot_priority C.6.8. rsu_slot_erase C.6.9. rsu_slot_program_buf C.6.10. rsu_slot_program_factory_update_buf C.6.11. rsu_slot_program_buf_raw C.6.12. rsu_slot_verify_buf C.6.13. rsu_slot_verify_buf_raw C.6.14. rsu_slot_enable C.6.15. rsu_slot_disable C.6.16. rsu_slot_load C.6.17. rsu_slot_load_factory C.6.18. rsu_slot_rename C.6.19. rsu_slot_delete C.6.20. rsu_slot_create C.6.21. rsu_status_log C.6.22. rsu_notify C.6.23. rsu_clear_error_status C.6.24. rsu_reset_retry_counter C.6.25. rsu_dcmf_version C.6.26. rsu_max_retry C.6.27. rsu_dcmf_status C.6.28. rsu_create_empty_cpb C.6.29. rsu_restore_cpb C.6.30. rsu_save_cpb C.6.31. rsu_restore_spt C.6.32. rsu_save_spt C.6.33. rsu_running_factory
C.7. RSU U-Boot Commands x
C.7.1. dtb C.7.2. list C.7.3. slot_by_name C.7.4. slot_count C.7.5. slot_disable C.7.6. slot_enable C.7.7. slot_erase C.7.8. slot_get_info C.7.9. slot_load C.7.10. slot_load_factory C.7.11. slot_priority C.7.12. slot_program_buf C.7.13. slot_program_buf_raw C.7.14. slot_program_factory_update_buf C.7.15. slot_rename C.7.16. slot_delete C.7.17. slot_create C.7.18. slot_size C.7.19. slot_verify_buf C.7.20. slot_verify_buf_raw C.7.21. status_log C.7.22. update C.7.23. notify C.7.24. clear_error_status C.7.25. reset_retry_counter C.7.26. display_dcmf_version C.7.27. display_dcmf_status C.7.28. display_max_retry C.7.29. restore_spt C.7.30. save_spt C.7.31. create_empty_cpb C.7.32. restore_cpb C.7.33. save_cpb C.7.34. check_running_factory
D. LIBRSU Reference Information x
D.1. Configuration File D.2. Error Codes D.3. Using LIBRSU Without a Valid SPT or CPB D.4. Macros D.5. Data Types D.6. Functions D.7. RSU Client Commands
D.5. Data Types x
D.5.1. rsu_slot_info D.5.2. rsu_status_info D.5.3. rsu_data_callback
D.6. Functions x
D.6.1. librsu_init D.6.2. librsu_exit D.6.3. rsu_slot_count D.6.4. rsu_slot_by_name D.6.5. rsu_slot_get_info D.6.6. rsu_slot_size D.6.7. rsu_slot_priority D.6.8. rsu_slot_erase D.6.9. rsu_slot_program_buf D.6.10. rsu_slot_program_factory_update_buf D.6.11. rsu_slot_program_file D.6.12. rsu_slot_program_factory_update_file D.6.13. rsu_slot_program_buf_raw D.6.14. rsu_slot_program_file_raw D.6.15. rsu_slot_verify_buf D.6.16. rsu_slot_verify_file D.6.17. rsu_slot_verify_buf_raw D.6.18. rsu_slot_verify_file_raw D.6.19. rsu_slot_program_callback D.6.20. rsu_slot_program_callback_raw D.6.21. rsu_slot_verify_callback D.6.22. rsu_slot_verify_callback_raw D.6.23. rsu_slot_copy_to_file D.6.24. rsu_slot_enable D.6.25. rsu_slot_disable D.6.26. rsu_slot_load_after_reboot D.6.27. rsu_slot_load_factory_after_reboot D.6.28. rsu_slot_rename D.6.29. rsu_slot_delete D.6.30. rsu_slot_create D.6.31. rsu_status_log D.6.32. rsu_notify D.6.33. rsu_clear_error_status D.6.34. rsu_reset_retry_counter D.6.35. rsu_dcmf_version D.6.36. rsu_max_retry D.6.37. rsu_dcmf_status D.6.38. rsu_save_spt D.6.39. rsu_restore_spt D.6.40. rsu_save_cpb D.6.41. rsu_create_empty_cpb D.6.42. rsu_restore_cpb D.6.43. rsu_running_factory
D.7. RSU Client Commands x
D.7.1. count D.7.2. list D.7.3. size D.7.4. priority D.7.5. enable D.7.6. disable D.7.7. request D.7.8. request-factory D.7.9. erase D.7.10. add D.7.11. add-factory-update D.7.12. add-raw D.7.13. verify D.7.14. verify-raw D.7.15. copy D.7.16. log D.7.17. notify D.7.18. clear-error-status D.7.19. reset-retry-counter D.7.20. display-dcmf-version D.7.21. display-dcmf-status D.7.22. display-max-retry D.7.23. create-slot D.7.24. delete-slot D.7.25. restore-spt D.7.26. save-spt D.7.27. create-empty-cpb D.7.28. restore-cpb D.7.29. save-cpb D.7.30. check-running-factory D.7.31. help
1. Overview
2. Use Cases
3. Quad SPI Flash Layout
4. Intel® Quartus® Prime Software and Tool Support
5. Software Support
6. Flash Corruption - Detection and Recovery
7. Remote System Update Example
8. Version Compatibility Considerations
9. Intel Agilex® 7 Hard Processor System Remote System Update User Guide Archives
10. Document Revision History for the Intel Agilex® 7 Hard Processor System Remote System Update User Guide
A. Configuration Flow Diagrams
B. RSU Status and Error Codes
C. U-Boot RSU Reference Information
D. LIBRSU Reference Information
E. Combined Application Images

B. RSU Status and Error Codes

The RSU status can be checked from U-Boot and Linux and contains the following 32-bit fields:
Table 11.   RSU Status Fields
Field Description
current_image Location of currently running image in flash.
failed_image Address of failed image.
error_details Opaque error code, with no meaning to users.
error_location Location of error in the image that failed.
state State of RSU system.
version RSU interface version and error source.
retry counter Current value of the retry counter.

The failed_image, error_details, error_location, state fields and the error_source bit field of the version field have a sticky behavior: they are set when an error occurs, then they are not updated on subsequent errors, and they are cleared when one of the following events occur: POR, nCONFIG, a specific image is loaded, or the error status is specifically cleared from either U-Boot or Linux.

The state field has two bit fields:
Table 12.  State fields
Bit Field Bits Description
major_error_code 31:16 Major error code, see below for possible values.
minor_error_code 15:0 Minor error code, opaque value

The following major error codes are defined:

Table 13.  RSU Major Error Codes
Major Error Code Description
0xF001 BITSTREAM_ERROR
0xF002 HARDWARE_ACCESS_FAILURE
0xF003 BITSTREAM_CORRUPTION
0xF004 INTERNAL_ERROR
0xF005 DEVICE_ERROR
0xF006 HPS_WATCHDOG_TIMEOUT
0xF007 INTERNAL_UNKNOWN_ERROR

The minor error code is typically an opaque value, with no meaning for you. The only exception is for the case where the major error code is 0xF006 (HPS_WATCHDOG_TIMEOUT), in which case the minor error code is the value reported by the HPS to SDM through the RSU Notify command before the watchdog timeout occurred.

Starting with Intel® Quartus® Prime Pro Edition software version 20.4, the following INTERNAL_ERROR codes are reported by the decision firmware and have specific meanings, as defined below:
Table 14.  Decision Firmware Error Codes
Major Error Code Minor Error Code Description
0xF004 0xD00F Decision firmware data was corrupted, factory image was loaded.
0xF004 0xD010 Configuration pointer block 0 was corrupted, configuration pointer block 1 was used instead.
0xF004 0xD011 Both configuration blocks 0 and 1 were corrupted, factory image was loaded.

For a more complete list of possible error codes, refer to Mailbox Client Intel FPGA IP User Guide, Appendix: CONFIG_STATUS and RSU_STATUS Error Code Descriptions .

The version component has the following bit fields:
Table 15.  Version fields
Bit Field Bits Description
current_dcmf_index 31:28 Index of the decision firmware copy that was used last time. Possible values: 0,1,2,3.
error_source 27:16 Source of the recorded error:
  • 0x000: for no error
  • 0xACF: if the error was produced by an application or factory image firmware
  • 0xDCF: if the error was produced by the decision firmware
acmf_version 15:8 Current image firmware RSU interface version.
dcmf_version 7:0 Decision firmware RSU interface version.
Note: Intel® Quartus® Prime Pro Edition version 20.1 is the first version which support RSU for Intel Agilex® 7, and both acmf_version and dcmf_version are set to 0x02 for this release.
Level Two Title