Hard Processor System Remote System Update User Guide: Agilex™ 5 SoCs

Download PDF
ID 852610
Date 4/18/2025
Public
Document Table of Contents
Document Table of Contents x
1. Overview 2. Use Cases 3. Quad SPI Flash Layout 4. 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. Revision History for the Hard Processor System Remote System Update User Guide: Agilex™ 5 SoCs 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
4. Quartus® Prime Software and Tool Support x
4.1. Quartus® Prime Pro Edition Software 4.2. Programming File Generator 4.3. Quartus® Prime Programmer 4.4. Supported QSPI Flash Devices
4.1. 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.1.4. Setting QSPI Ownership
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 Configuration First 4.2.3.1.2. Creating Initial Flash Image for HPS Boot 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. Altera™ Service Driver 5.4.2. Altera™ 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
8. Version Compatibility Considerations x
8.1. Component Versions 8.2. Component Interfaces 8.3. Component Version Compatibility 8.4. Using Multiple Quartus® Prime Software Versions for Bitstreams 8.5. Updating U-Boot to Support Different SSBL per Bitstream
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. Operative System Abstraction Layer Data Types D.5.2. rsu_slot_info D.5.3. rsu_status_info D.5.4. rsu_data_callback
D.6. Functions x
D.6.1. rsu_slot_priority D.6.2. rsu_slot_erase D.6.3. rsu_slot_program_buf D.6.4. rsu_slot_program_factory_update_buf D.6.5. rsu_slot_program_file D.6.6. rsu_slot_program_factory_update_file D.6.7. rsu_slot_program_buf_raw D.6.8. rsu_slot_program_file_raw D.6.9. rsu_slot_verify_buf D.6.10. rsu_slot_verify_file D.6.11. rsu_slot_verify_buf_raw D.6.12. rsu_slot_verify_file_raw D.6.13. rsu_slot_program_callback D.6.14. rsu_slot_program_callback_raw D.6.15. rsu_slot_verify_callback D.6.16. rsu_slot_verify_callback_raw D.6.17. rsu_slot_copy_to_file D.6.18. rsu_slot_enable D.6.19. rsu_slot_disable D.6.20. rsu_slot_load_after_reboot D.6.21. rsu_slot_load_factory_after_reboot D.6.22. rsu_slot_rename D.6.23. rsu_slot_delete D.6.24. rsu_slot_create D.6.25. rsu_status_log D.6.26. rsu_notify D.6.27. rsu_clear_error_status D.6.28. rsu_reset_retry_counter D.6.29. rsu_dcmf_version D.6.30. rsu_max_retry D.6.31. rsu_dcmf_status D.6.32. rsu_save_spt D.6.33. rsu_restore_spt D.6.34. rsu_save_cpb D.6.35. rsu_create_empty_cpb D.6.36. rsu_restore_cpb D.6.37. 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. 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. Revision History for the Hard Processor System Remote System Update User Guide: Agilex™ 5 SoCs
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.2. System Components

This section describes the components in a typical Linux system. The components in this system are described in the following figure and table.

Figure 2. System Components

The bitstream is stored in the configuration flash device (QSPI) connected to the SDM pins. The HPS software is typically stored in a mass storage flash device (SD/eMMC/ NAND) connected to the HPS pins but can also be stored in the flash device connected to the SDM pins.

Table 1.  System Components
Component Description
FPGA Configuration Data When using FPGA first mode, this component of the bitstream contains the full FPGA and I/O configuration data. When using HPS first mode, it contains just the HPS and HPS EMIF I/Os.
SDM Firmware

Firmware for the Secure Device Manager

Provides commands for managing RSU. These commands are not directly accessible to you. Instead both U-Boot and Linux* offer services for accessing the functionality offered by the SDM commands indirectly.

U-Boot SPL

The HPS First Stage Bootloader

Initializes hardware including the SDRAM and loads the HPS Second Stage Bootloader.

ATF

Arm Trusted Firmware

Provides secure services to U-Boot and Linux through Secure Monitor Call (SMC).6

U-Boot

HPS Second Stage Bootloader:

  • Loads and boots the operating system
  • Provides RSU APIs and command line capabilities.
  • Uses ATF SMC calls to indirectly access the SDM services.
Linux* Drivers

Altera™ RSU driver uses the functionality provided by U-Boot SMC and makes services available to applications running on Linux*.

LIBRSU

Linux* user space library providing APIs for managing RSU.

RSU Client

Linux* sample application which uses LIBRSU for managing RSU.

Altera™ provides an RSU solution that focuses on the reliable update of the components that are part of the configuration bitstream, and are located in SDM flash. It is your responsibility to devise a scheme for the reliable update of the rest of the system components.

When RSU flow is exercised from the HPS software, the HPS must get the ownership of the QSPI, which typically is done by the HPS first stage bootloader.

For information about version compatibility requirements of various system components, refer to the Version Compatibility Considerations section.

Related Information
6 On Cortex* -A55/ Cortex* -A76, there are four execution levels: EL0-Application, EL1-OS, EL2-Hypervisor, and EL3-Secure Monitor. Interacting with SDM is only allowed for software running at EL3. ATF runs at EL3, U-Boot and Linux* run at EL1. For U-Boot and Linux* to communicate with the SDM, they have to issue an SMC trap to a handler left resident by ATF. Then that handler runs at EL3 and is able to communicate with the SDM.
Level Two Title