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.1. Using U-Boot to Perform Basic Operations

This section demonstrates how to use U-Boot to perform the following basic operations:
  • Querying the RSU status.
  • Querying the number of slots and the information about them.
  • Adding a new application image.
  • Verifying that an application image was written correctly.
  • Requesting a specific application image to be loaded.
Note: This section assumes that the flash contains the initial RSU image. If that is not true, you need to re-flash the initial image, as shown in the Flashing the Initial RSU Image to QSPI .
  1. Power cycle the board and press any key when prompted, to get to the U-Boot command prompt: 
    U-Boot 2021.01-12712-ge59d8e9eaa-dirty (Jun 30 2021 - 10:40:17 -0500)socfpga_agilex

CPU:   Intel FPGA SoCFPGA Platform (ARMv8 64bit Cortex-A53)
Model: SoCFPGA Agilex SoCDK
DRAM:  8 GiB
WDT:   Started with servicing (10s timeout)
MMC:   dwmmc0@ff808000: 0
Loading Environment from MMC... *** Warning - bad CRC, using default environment

In:    serial0@ffc02000
Out:   serial0@ffc02000
Err:   serial0@ffc02000
Net:   
Warning: ethernet@ff800000 (eth0) using random MAC address - 62:08:b9:b7:79:2d
eth0: ethernet@ff800000
Hit any key to stop autoboot:  5 

 0 
SOCFPGA #
  2. Run the rsu command without parameters, to display its help message, and usage options: 
    SOCFPGA # rsu
rsu - Agilex SoC Remote System Update

Usage:
rsu dtb   - Update Linux DTB qspi-boot parition offset with spt0 value
list  - List down the available bitstreams in flash
slot_by_name <name> - find slot by name and display the slot number
slot_count - display the slot count
slot_disable <slot> - remove slot from CPB
slot_enable <slot> - make slot the highest priority
slot_erase <slot> - erase slot
slot_get_info <slot> - display slot information
slot_load <slot> - load slot immediately
slot_load_factory - load factory immediately
slot_priority <slot> - display slot priority
slot_program_buf <slot> <buffer> <size> - program buffer into slot, and make it highest priority
slot_program_buf_raw <slot> <buffer> <size> - program raw buffer into slot
slot_program_factory_update_buf <slot> <buffer> <size> - program factory update buffer into slot, and make it highest priority
slot_rename <slot> <name> - rename slot
slot_size <slot> - display slot size
slot_verify_buf <slot> <buffer> <size> - verify slot contents against buffer
slot_verify_buf_raw <slot> <buffer> <size> - verify slot contents against raw buffer
status_log - display RSU status
update <flash_offset> - Initiate firmware to load bitstream as specified by flash_offset
notify <value> - Let SDM know the current state of HPS software
clear_error_status - clear the RSU error status
reset_retry_counter - reset the RSU retry counter
display_dcmf_version - display DCMF versions and store them for SMC handler usage 
display_dcmf_status - display DCMF status and store it for SMC handler usage
display_max_retry - display max_retry parameter, and store it for SMC handler usage
restore_spt <address> - restore SPT from an address
save_spt <address> - save SPT to an address
create_empty_cpb - create a empty CPB
restore_cpb <address> - restore CPB from an address
save_cpb <address> - save CPB to an address
check_running_factory - check if currently running the factory image
  3. Run the rsu list command to display the RSU partitions, CPBs, the currently running image and the status: 
    SOCFPGA # rsu list
RSU: Remote System Update Status
Current Image    : 0x01000000
Last Fail Image  : 0x00000000
State            : 0x00000000
Version          : 0x00000202
Error location   : 0x00000000
Error details    : 0x00000000
Retry counter    : 0x00000000
RSU: Sub-partition table 0 offset 0x00910000
RSU: Sub-partition table 1 offset 0x00918000
SF: Detected mt25qu02g with page size 256 Bytes, erase size 4 KiB, total 256 MiB
RSU: Sub-partition table content
       BOOT_INFO	Offset: 0x0000000000000000	Length: 0x00210000	Flag : 0x00000003
   FACTORY_IMAGE	Offset: 0x0000000000210000	Length: 0x00700000	Flag : 0x00000003
              P1	Offset: 0x0000000001000000	Length: 0x01000000	Flag : 0x00000000
            SPT0	Offset: 0x0000000000910000	Length: 0x00008000	Flag : 0x00000001
            SPT1	Offset: 0x0000000000918000	Length: 0x00008000	Flag : 0x00000001
            CPB0	Offset: 0x0000000000920000	Length: 0x00008000	Flag : 0x00000001
            CPB1	Offset: 0x0000000000928000	Length: 0x00008000	Flag : 0x00000001
              P2	Offset: 0x0000000002000000	Length: 0x01000000	Flag : 0x00000000
              P3	Offset: 0x0000000003000000	Length: 0x01000000	Flag : 0x00000000
RSU: CMF pointer block offset 0x00920000
RSU: CMF pointer block's image pointer list
Priority 1 Offset: 0x0000000001000000 nslot: 0
    Note: The rsu list U-Boot command does not have a RSU client equivalent. Instead, the same information can be retrieved using other commands, as shown next.
  4. Run the rsu status_log command to 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

    Application image P1 is loaded, as it is the highest priority in the CPB. There are no errors.

  5. Run the rsu display_dcmf_version to query and display the decision firmware versions: 
    SOCFPGA # rsu display_dcmf_version
DCMF0 version = 21.2.0
DCMF1 version = 21.2.0
DCMF2 version = 21.2.0
DCMF3 version = 21.2.0
  6. Display information about the slots: 
    SOCFPGA # rsu slot_count
Number of slots = 3.
SOCFPGA # rsu slot_get_info 0
NAME: P1
OFFSET: 0x0000000001000000
SIZE: 0x01000000
PRIORITY: 1
SOCFPGA # rsu slot_get_info 1
NAME: P2
OFFSET: 0x0000000002000000
SIZE: 0x01000000
PRIORITY: [disabled]
SOCFPGA # rsu slot_get_info 2
NAME: P3
OFFSET: 0x0000000003000000
SIZE: 0x01000000
PRIORITY: [disabled]
SOCFPGA # rsu slot_size 0
Slot 0 size = 16777216.
SOCFPGA # rsu slot_size 1
Slot 1 size = 16777216.
SOCFPGA # rsu slot_size 2
Slot 2 size = 16777216.
  7. Erase slot 1 and add the application2.rpd image to slot 1: 
    SOCFPGA # rsu slot_erase 1
Slot 1 erased
SOCFPGA # load mmc 0:1 $loadaddr application2.rpd
3358720 bytes read in 153 ms (20.9 MiB/s)
SOCFPGA # rsu slot_program_buf 1 $loadaddr $filesize
Slot 1 was programmed with buffer=0x0000000002000000 size=3358720.
  8. Verify that the application image was written correctly: 
    SOCFPGA # rsu slot_verify_buf 1 $loadaddr $filesize
Slot 1 was verified with buffer=0x0000000002000000 size=3358720.
  9. Confirm that slot 1 (partition P2) contains now the highest priority image: 
    SOCFPGA # rsu slot_get_info 1
NAME: P2
OFFSET: 0x0000000002000000
SIZE: 0x01000000
PRIORITY: 1
  10. Power-cycle the board, stop U-Boot and check the RSU status log: 
    SOCFPGA # rsu status_log         
Current Image   : 0x02000000
Last Fail Image : 0x00000000
State           : 0x00000000
Version         : 0x00000202
Error location  : 0x00000000
Error details   : 0x00000000
Retry counter   : 0x00000000

    The application image from slot 1 (partition P2) was loaded, because it is marked as the highest priority in the CPB.

  11. Load the application image from slot 0 (partition P1) by running any of the following two commands: 
    SOCFPGA # rsu update 0x01000000
RSU: RSU update to 0x0000000001000000
    or 
    SOCFPGA # rsu slot_load 0
  12. Load the newly requested image. Stop at U-Boot prompt and check the status log to confirm it: 
    SOCFPGA # rsu status_log
Current Image   : 0x01000000
Last Fail Image : 0x00000000
State           : 0x00000000
Version         : 0x00000202
Error location  : 0x00000000
Error details   : 0x00000000
Retry counter   : 0x00000000
    Note: In U-Boot, the effect of requesting a specific image is immediate. On Linux, it only takes effect on the next reboot command.
Related Information
Level Two Title