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.5.1. Using the RSU Client to Perform Basic Operations

This section demonstrates how to use the RSU client 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 the 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 section.
  1. Power cycle the board and let Linux* boot.
  2. Log in using ‘root’ as user name, no password is required.
  3. Run the rsu_client without parameters, to display its help message: 
    root@linux:~# ./rsu_client 
--- RSU app usage ---
-c|--count                        get the number of slots
-l|--list slot_num                list the attribute info from the selected slot
-z|--size slot_num                get the slot size in bytes
-p|--priority slot_num            get the priority of the selected slot
-E|--enable slot_num              set the selected slot as the highest priority
-D|--disable slot_num             disable selected slot but to not erase it
-r|--request slot_num             request the selected slot to be loaded after the next reboot
-R|--request-factory              request the factory image to be loaded after the next reboot
-e|--erase slot_num               erase app image from the selected slot
-a|--add file_name -s|--slot slot_num  add a new app image to the selected slot
-u|--add-factory-update file_name -s|--slot slot_num  add a new factory update image to the selected slot
-A|--add-raw file_name -s|--slot slot_num  add a new raw image to the selected slot
-v|--verify file_name -s|--slot slot_num  verify app image on the selected slot
-V|--verify-raw file_name -s|--slot slot_num  verify raw image on the selected slot
-f|--copy file_name -s|--slot slot_num  read the data in a selected slot then write to a file
-g|--log                          print the status log
-n|--notify value                 report software state
-C|--clear-error-status           clear errors from the log
-Z|--reset-retry-counter          reset current retry counter
-m|--display-dcmf-version         print DCMF version
-y|--display-dcmf-status          print DCMF status
-x|--display-max-retry            print max_retry parameter
-t|--create-slot slot_name -S|--address slot_address -L|--length slot_size  create a new slot using unallocated space
-d|--delete-slot slot_num         delete selected slot, freeing up allocated space
-W|--restore-spt file_name        restore spt from a file
-X|--save-spt file_name           save spt to a file
-b|--create-empty-cpb             create a empty cpb
-B|--restore-cpb file_name        restore cpb from a file
-P|--save-cpb file_name           save cpb to a file
-k|--check-running-factory        check if currently running the factory image
-h|--help                         show usage message
  4. Exercise the rsu_client command that displays the current status, it shows the application image from slot 0 (partition P1) is loaded with no errors: 
    root@linux:~# ./rsu_client --log
      VERSION: 0x00000202
        STATE: 0x00000000
CURRENT IMAGE: 0x0000000001000000
   FAIL IMAGE: 0x0000000000000000
    ERROR LOC: 0x00000000
ERROR DETAILS: 0x00000000
RETRY COUNTER: 0x00000000
Operation completed
  5. Run the RSU client commands that display information about the slots: 
    root@linux:~# ./rsu_client --count
number of slots is 3
Operation completed
root@linux:~# ./rsu_client --list 0
      NAME: P1
    OFFSET: 0x0000000001000000
      SIZE: 0x01000000
  PRIORITY: 1
Operation completed
root@linux:~# ./rsu_client --list 1
      NAME: P2
    OFFSET: 0x0000000002000000
      SIZE: 0x01000000
  PRIORITY: [disabled]
Operation completed
root@linux:~# ./rsu_client --list 2
      NAME: P3
    OFFSET: 0x0000000003000000
      SIZE: 0x01000000
  PRIORITY: [disabled]
Operation completed
  6. Display the decision firmware version information: 
    root@linux:~# ./rsu_client --display-dcmf-version
DCMF0 version = 21.2.0
DCMF1 version = 21.2.0
DCMF2 version = 21.2.0
DCMF3 version = 21.2.0
Operation completed
  7. Erase slot 1 and add the application2.rpd application image to slot 1 (partition P2): 
    root@linux:~# ./rsu_client --erase 1
Operation completed
root@linux:~# ./rsu_client --add application2.rpd --slot 1
Operation completed
  8. Verify that the application image was written correctly to flash: 
    root@linux:~# ./rsu_client --verify application2.rpd --slot 1
Operation completed
  9. List again the slots, it shows the most recently written partition P2 image having the highest priority (lowest priority number that is): 
    root@linux:~# ./rsu_client --list 0
      NAME: P1
    OFFSET: 0x0000000001000000
      SIZE: 0x01000000
  PRIORITY: 2
Operation completed
root@linux:~# ./rsu_client --list 1
      NAME: P2
    OFFSET: 0x0000000002000000
      SIZE: 0x01000000
  PRIORITY: 1
Operation completed
root@linux:~# ./rsu_client --list 2
      NAME: P3
    OFFSET: 0x0000000003000000
      SIZE: 0x01000000
  PRIORITY: [disabled]
Operation completed
  10. Power cycle the board, boot Linux*, and display the status – it shows the image from partition P2 running: 
    root@linux:~# ./rsu_client --log
      VERSION: 0x00000202
        STATE: 0x00000000
CURRENT IMAGE: 0x0000000002000000
   FAIL IMAGE: 0x0000000000000000
    ERROR LOC: 0x00000000
ERROR DETAILS: 0x00000000
RETRY COUNTER: 0x00000000
Operation completed
  11. Instruct the RSU client to request slot 0 (partition P1) from SDM on next reboot command: 
    root@linux:~# ./rsu_client --request 0
Operation completed
  12. Restart Linux* by running the reboot command: 
    root@linux:~# reboot
  13. Log into Linux* and display the RSU status: 
    root@linux:~# ./rsu_client --log
      VERSION: 0x00000202
        STATE: 0x00000000
CURRENT IMAGE: 0x0000000001000000
   FAIL IMAGE: 0x0000000000000000
    ERROR LOC: 0x00000000
ERROR DETAILS: 0x00000000
RETRY COUNTER: 0x00000000
Operation completed

    The status shows that the image from partition P1 was loaded, as requested.

Level Two Title