4.8.1 Updating the Application Using a Bootloader Client With Multiple Images and Anti-Rollback Protection

This section demonstrates how to configure the application for a bootloader client with multiple image and anti-rollback protection support.

Description: This section details how to update the data in the footer_certificate.c file and configure the linker settings of the application project for multi-image support.

1. Create a new file or open the existing footer_certificate.c file from the application project.

   Note: The application builder automatically generates this file.

   

2. Add the following macros at top of the file and update the image ID for the backup image according to the configuration on the MDFU client UI. For this example, the backup image ID is 3.

   Note: The execution image ID will always be 0x0000.

   #define EXECUTION_IMAGE_ID 0x0000
   #define BACKUP_IMAGE_ID 0x0003
   

3. Add the following code after the macro definitions .

   volatile const uint16_t
   #ifdef __XC8__
   __at(0x9AF0)
   #endif
   applicationId __attribute__((used, section("app_id"))) = EXECUTION_IMAGE_ID;
   
   volatile const uint32_t
   #ifdef __XC8__
   __at(0x9AF2)
   #endif
   applicationVersion __attribute__((used, section("app_version"))) = 0x00000300;
   
   volatile const uint32_t
   #ifdef __XC8__
   __at(0x9AF6)
   #endif
   verificationEndAddress __attribute__((used, section("crc_end_address"))) = 0x00009AFD;
   
   volatile const uint32_t
   #ifdef __XC8__
   __at(0x9AFA)
   #endif
   verificationStartAddress __attribute__((used, section("crc_start_address"))) = 0x00002400;
   

   Understanding the variables stored in the footer data in the Flash memory:

   Table 4-3. Footer Certificate Data

   Variable	Purpose	Address
   applicationId	This is the location where the current image will be stored. Current Example Value: EXECUTION_IMAGE_ID Should be: Image ID of the image location to update	The address in the __at() is calculated by subtracting 2 from the start address of the applicationVersion. The two bytes are used for storing the uint16_t type variable applicationId. This value might change for your application.
   applicationVersion	This is the version of the current application. Current Example Value: 0x00000300 Should be: Version of the application Warning: Application version cannot be 0 or 4294967295 (0xFFFFFFFF).	The address in the __at() is calculated by subtracting 4 from the start address of the verificationEndAddress The four bytes are used for storing the uint32_t type variable applicationVersion. If rollback protection is enabled, this value must be updated whenever a new application image needs to be loaded.
   verificationEndAddress	This is the last address that is considered for the hash calculation mapped into the execution space. The value of this argument must always fall within the execution space. Current Example Value: 0x00009AFD Should be: Execution Image End Address	The address in the __at() is calculated by subtracting 4 from the start address of the verificationStartAddress The four bytes are used for storing the uint32_t type varible verificationEndAddress. This value might change for your application.
   verificationStartAddress	This is the first address that is considered for the hash calculation mapped into the execution space. The value of this argument must always fall within the execution space. Current Example Value: 0x00002400 Should be: Execution Image Start Address	The address in the __at() is calculated by subtracting 6 from the end address of the application image to be verified. The six bytes are the sum of the two bytes for storing the checksum and four bytes for storing the uint32_t type variable verificationStartAddress. Tip: Populate the addresses following a bottom-up approach for easier calculations. This value might change for your application.

4. Add the following code in the footer_certificate.c file after the macros. This reserves the last bytes to hold the Checksum value. The address presented below in the __at() is the execution image end address - 2, since the Checksum hash size used is two bytes and we are locating the end of the application to be the execution space. This address may be different for your device.

   
   volatile const uint16_t
   #ifdef __XC8__
   __at(0x9AFE)
   #endif
   checksumStart __attribute__((used, section("checksum_data"))) = 0xFFFF;
   

   Tip: For more information on how to define this variable, refer point 9 from Creating an Application for PIC® Devices.
5. Additionally, linker settings need to be updated to restrict the ROM range to the current application image ID’s Flash range.
   • PIC devices:

     

     Where 2400-9AFF is <applicationId image start address: applicationId image end address>. These values can be updated by referring to the Device Flash Memory Partitions Table in the MDFU Client UI and the applicationId.

   • AVR device linker settings:

     For an AVR based bootloader client with applicationid image range of 0x2400-0x9AFF the linker settings are as follows:

     • XC8 linker settings:

       Open Project Properties>XC8 Linker>Additional Options. In the “Additional Options” text box, add -Wl,-u,checksumStart,-u,verificationStartAddress,-u,verificationEndAddress,-u,applicationVersion,-u,applicationId,-u,__TEXT_REGION_LENGTH__=<applicationId image start address: applicationId image end address>,-Ttext=<applicationId image start>.

       

     • GCC linker settings:

       Open Project Properties>Avr GCC (Global Options)>avr-ld>General. In the “Additional Options” text box, add -Wl,-u,checksumStart,-u,verificationStartAddress,-u,verificationEndAddress,-u,applicationVersion,-u,applicationId,-u,__TEXT_REGION_LENGTH__=<applicationId image start address: applicationId image end address>,-Ttext=<applicationId image start>.