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

3.2.4. Application Image Layout

The application image comprises SDM firmware and the configuration data. The configuration data includes up to four sections. The SDM firmware contains pointers to those sections. The table below shows the location of the number of sections and the section pointers in a application image.

Table 8.  Application Image Section Pointers
Offset Size (in bytes) Description
0x1F00 4 Number of sections
  …  
0x1F08 8 Address of 1st section
0x1F10 8 Address of 2nd section
0x1F18 8 Address of 3rd section
0x1F20 8 Address of 4th section
  …  
0x1FFC 4 CRC32 of 0x1000 to 0x1FFB

The section pointers must match the actual location of the FPGA image in flash. Two options are available to meet this requirement:

  • You can generate the application image to match the actual location in quad SPI flash memory. This option may not be practical as different systems may have a different set of updates applied, which may result in different slots being suitable to store the new application image.
  • You can generate the application image as if it is located at address zero, then update the pointers to match the actual location.
    • In Intel® Quartus® Prime software version 21.1 or later, a Use relative address option is the default option to generate a single application bitstream. You do not have to specify the start address since you can program the image to any available location in the QSPI flash memory. To load the image, you must correctly point to the starting address of the stored image in the flash memory.

      If you choose to disable this option, unselect the Use relative address checkbox and provide the Start address for the image in flash memory. For more information, refer to Generating an Application Image in the Intel® Stratix® 10 Configuration User Guide.

When using the HPS to manage RSU, both U-Boot and LIBRSU clients implement the below procedure to relocate application images targeting address zero in the actual destination slot address.

The procedure to update the pointers from an application image created for INITIAL_ADDRESS to NEW_ADDRESS is:
  1. Create the application image, targeting the INITIAL_ADDRESS.
  2. Read the 32-bit value from offset 0x1F00 of the application image to determine the number of sections.
  3. For <s>= 1 to number_of_sections:
    1. section_pointer = read the 64-bit section pointer from 0x1F00 + (s * 8)
    2. Subtract INITIAL_ADDRESS from section_pointer
    3. Add NEW_ADDRESS to section_pointer
    4. Store updated section_pointer
  4. Recompute the CRC32 for addresses 0x1000 to 0x1FFB. Store the new value at offset 0x1FFC. The CRC32 value must be computed on a copy of the data using the following procedure:
    1. Swap the bits of each byte so that the bits occur in reverse order and compute the CRC.
    2. Swap the bytes of the computed CRC32 value to appear in reverse order.
    3. Swap the bits in each byte of the CRC32 value.
    4. Write the CRC32 value to flash.

For more information, refer to Creating the Application Image.

Note: The factory update image has a different format, which requires a different procedure for the pointer updates. When using the HPS to manage RSU, both U-Boot and LIBRSU clients implement this procedure for relocating the factory update image.
Note: The combined application image has a different format, with no pointers that need to be relocated. The image can be placed unmodified in flash at any address.
Related Information
Level Two Title