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

Download PDF
ID 683184
Date 7/13/2022
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. Using RSU with HPS First A. Configuration Flow Diagrams B. RSU Status and Error Codes C. U-Boot RSU Reference Information D. LIBRSU Reference Information E. Combined Application Images 10. Document Revision History for the SoC Remote System Update User Guide
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. 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
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. Prerequisites 7.2. Building RSU Example Binaries 7.3. Flashing the Binaries 7.4. Exercising U-Boot RSU Commands 7.5. Exercising the RSU Client
7.2. Building RSU Example Binaries x
7.2.1. Setting up the Environment 7.2.2. Building the Hardware Projects 7.2.3. Building Arm* Trusted Firmware 7.2.4. Building U-Boot 7.2.5. Creating the Initial Flash Image 7.2.6. Creating the Application Image 7.2.7. Creating the Factory Update Image 7.2.8. Creating the Decision Firmware Update Image 7.2.9. Building Linux* 7.2.10. Building ZLIB 7.2.11. Building LIBRSU and RSU Client 7.2.12. Building the Root File System 7.2.13. Building the SD Card
7.3. Flashing the Binaries x
7.3.1. Flashing the Initial RSU Image to QSPI 7.3.2. Writing the SD Card Image
7.4. Exercising U-Boot RSU Commands x
7.4.1. Using U-Boot to Perform Basic Operations 7.4.2. Watchdog and Max Retry Operation 7.4.3. Updating the Factory Image Using U-Boot 7.4.4. Fallback on Flash Corruption of Application Images 7.4.5. Additional Flash Corruption Detection and Recovery
7.4.5. Additional Flash Corruption Detection and Recovery x
7.4.5.1. Corrupted Decision Firmware 7.4.5.2. Corrupted Decision Firmware Data 7.4.5.3. Corrupted Configuration Pointer Block 7.4.5.4. Corrupted Sub-Partition Table
7.5. Exercising the RSU Client x
7.5.1. Using the RSU Client to Perform Basic Operations 7.5.2. Watchdog Timeout and max retry Operation 7.5.3. Updating the Factory Image Using the RSU Client 7.5.4. Fallback on Flash Corruption of Application Images 7.5.5. Additional Flash Corruption Detection and Recovery
7.5.5. Additional Flash Corruption Detection and Recovery x
7.5.5.1. Corrupted Decision Firmware 7.5.5.2. Corrupted Decision Firmware Data 7.5.5.3. Corrupted Configuration Pointer Block 7.5.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
9. Using RSU with HPS First x
9.1. Update Hardware Designs to use HPS First 9.2. Creating Initial Flash Image for HPS First 9.3. Creating Application and Update Images for HPS First
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
E. Combined Application Images x
E.1. Creating the Combined Application Image E.2. Using the Combined Application Image
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. Using RSU with HPS First
A. Configuration Flow Diagrams
B. RSU Status and Error Codes
C. U-Boot RSU Reference Information
D. LIBRSU Reference Information
E. Combined Application Images
10. Document Revision History for the SoC Remote System Update User Guide

7.4.5.1. Corrupted Decision Firmware

This example uses U-Boot commands to demonstrate detecting that a decision firmware copy is corrupted, and recovering it by running a decision firmware update image.
Note: The commands listed in this example assume the initial flash image (JIC) was written to flash, with no other changes.
  1. Power cycle the board, boot to U-Boot prompt.
  2. Display the RSU status: 
    SOCFPGA # rsu status_log
Current Image   : 0x01000000
Last Fail Image : 0x00000000
State           : 0x00000000
Version         : 0x00000202
Error location  : 0x00000000
Error details   : 0x00000000
Retry counter   : 0x00000000

    The top four bits of the state field are 0x0 which means the currently used decision firmware index is zero. There are no errors.

  3. Display the decision firmware status: 
    SOCFPGA # rsu display_dcmf_status
DCMF0: OK
DCMF1: OK
DCMF2: OK
DCMF3: OK

    The command compares the currently used decision firmware copy 0 with the other copies, and displays that all decision firmware copies are fine.

  4. Corrupt decision firmware copies 0 and 2: 
    SOCFPGA # sf probe
SF: Detected mt25qu02g with page size 256 Bytes, erase size 4 KiB, total 256 MiB
SOCFPGA # sf erase 0 0x1000
SF: 4096 bytes @ 0x0 Erased: OK
SOCFPGA # sf erase 0x80000 0x1000
SF: 4096 bytes @ 0x80000 Erased: OK
  5. Power cycle the board, boot to U-Boot prompt, display the RSU status and decision firmware status: 
    SOCFPGA # rsu status_log
Current Image   : 0x01000000
Last Fail Image : 0x00000000
State           : 0x00000000
Version         : 0x10000202
Error location  : 0x00000000
Error details   : 0x00000000
Retry counter   : 0x00000000
SOCFPGA # rsu display_dcmf_status
DCMF0: Corrupted
DCMF1: OK
DCMF2: Corrupted
DCMF3: OK

    The currently used copy of the decision firmware is 1, as indicated by top four bits of the version field. The decision firmware copies 0 and 2 are detected as corrupted.

  6. Erase an unused slot, add the decision firmware update image to the slot, verify it was written fine, and confirm it is now the highest priority slot: 
    SOCFPGA # rsu slot_erase 2
Slot 2 erased.
SOCFPGA # fatload mmc 0:1 ${loadaddr} decision_firmware_update.rpd
151552 bytes read in 9 ms (16.1 MiB/s)
SOCFPGA # rsu slot_program_factory_update_buf 2 ${loadaddr} ${filesize}
Slot 2 was programmed with buffer=0x0000000002000000 size=151552.
SOCFPGA # rsu slot_verify_buf 2 ${loadaddr} ${filesize}
Slot 2 was verified with buffer=0x0000000002000000 size=151552.
SOCFPGA # rsu slot_get_info 2
NAME: P3
OFFSET: 0x0000000003000000
SIZE: 0x01000000
PRIORITY: 1
  7. Pass control to the devision firmware update image: 
    SOCFPGA # rsu slot_load 2
  8. The decision firmware update image writes new decision firmware copies and new decision firmware data to flash, remove itself from CPB, then pass control to the highest priority image.
  9. Stop at U-Boot prompt and confirm the decision firmware copies are all good, the decision firmware update image was removed from CPB, and the highest priority image is running: 
    SOCFPGA # rsu status_log 
Current Image   : 0x01000000
Last Fail Image : 0x00000000
State           : 0x00000000
Version         : 0x00000202
Error location  : 0x00000000
Error details   : 0x00000000
Retry counter   : 0x00000000
SOCFPGA # rsu display_dcmf_status
DCMF0: OK
DCMF1: OK
DCMF2: OK
DCMF3: OK
SOCFPGA # rsu slot_get_info 2
NAME: P3
OFFSET: 0x0000000003000000
SIZE: 0x01000000
PRIORITY: [disabled]
Level Two Title