1.9.6.1 Adding Application Header Fields

Often, users will want to add extra fields to the application header that the bootloader can use to make more decisions about the application file. This section of the help file shows how to read the custom headers added to the application header. Details on adding these headers to the application can be found in the Bootloader::Application help file. The user data being added is shown below:

  1. A single 16 Bit (2 Byte) Customer ID Value (BOOT_APPLICATION_ID_CUSTOMER_16_BIT_VALUE)
  2. A single 32 Bit (4 Byte) Customer ID Value (BOOT_APPLICATION_ID_CUSTOMER_32_BIT_VALUE)
  3. A 12 Byte string containing a date (BOOT_APPLICATION_ID_CUSTOMER_BUILD_DATE)

There are 4 steps to adding code to read these headers

  1. Add the header field names to the enum BOOT_APPLICATION_DETAIL_ID list located in the file boot/boot_application_header.h
  2. Add the parsing functions for each new Application Header
  3. Add the prototypes for each new Application Header parsing function
  4. Then calling these functions to retrieve the data values from the Application Header

Step 1: Adding the Header ID values to BOOT_APPLICATION_DETAIL_ID

Each header added to the application must have a unique ID. The bootloader expects the ID of each Application Header in the BOOT_APPLICATION_DETAIL_ID list located in the boot/application_header.h file. The updated version, containing the legacy VERSION_NUMBER ID as well as three new ones, is shown below:

enum BOOT_APPLICATION_DETAIL_ID
{
    BOOT_APPLICATION_DETAIL_ID_VERSION_NUMBER = 0x0002,
    BOOT_APPLICATION_ID_CUSTOMER_16_BIT_VALUE = 0x0003,
    BOOT_APPLICATION_ID_CUSTOMER_32_BIT_VALUE = 0x0004,
    BOOT_APPLICATION_ID_CUSTOMER_BUILD_DATE   = 0x0005
};

Step 2 Adding Functions to Read Each Application Header

The code below demonstrates how to create functions to read the data element in each Application Header. These functions are helper functions that call the BOOT_ApplicationDetailGet() function with the correct parameters and should be placed in the boot/boot_application_header.c file. BOOT_ApplicationDetailGet will start at the top of the header and scan for the desired application header. If the requested header is found, the actual data will be placed in the given buffer, and the function will return true.

// Read the 16 Bit number from the application header and return true if it was found in the header */
bool BOOT_Customer16BitNumberGet(enum BOOT_IMAGE image, uint16_t *number16Bit)
{
    memset(number16Bit, 0x00, sizeof(uint16_t));
    // Get the customer 16 bit value from the header.  BOOT_APPLICATION_ID_CUSTOMER_16_BIT_VALUE == 3;
    return BOOT_ApplicationDetailGet(image, 
                        BOOT_APPLICATION_ID_CUSTOMER_16_BIT_VALUE, (uint16_t*)number16Bit, sizeof(uint16_t));
}

// Read the 32 Bit number from the application header and return true if it was found in the header */
bool BOOT_Customer32BitNumberGet(enum BOOT_IMAGE image, uint32_t *number32Bit)
{
    memset(number32Bit, 0x00, sizeof(uint32_t));
    // Get the customer 32 bit value from the header.   BOOT_APPLICATION_ID_CUSTOMER_32_BIT_VALUE == 4;
    return BOOT_ApplicationDetailGet(image, 
                        BOOT_APPLICATION_ID_CUSTOMER_32_BIT_VALUE, (uint16_t*)number32Bit, sizeof(uint32_t));
}

// Read the Build Date of the application the application header and return true if it was found in the header */
bool BOOT_CustomerBuildDateGet(enum BOOT_IMAGE image, char *buildDateBuffer)
{
    memset(buildDateBuffer, 0x00, 12);
    // Get build date of the application in text form Mmm dd yyyy  from the header. 
    //                 BOOT_APPLICATION_ID_CUSTOMER_BUILD_DATE = 5 ;
    return BOOT_ApplicationDetailGet(image, 
                        BOOT_APPLICATION_ID_CUSTOMER_BUILD_DATE, (uint16_t*)buildDateBuffer, 12);
}

Step 3: Add the prototypes for each of the three functions mentioned above to the file boot/boot_application_header.h.

/* Format of 16 bit number is 0x0000 */
bool BOOT_Customer16BitNumberGet(enum BOOT_IMAGE image, uint16_t *number16Bit);

/* Format of 32 bit number is 0x00000000 */
bool BOOT_Customer32BitNumberGet(enum BOOT_IMAGE image, uint32_t *number32Bit);

/* Format of the string is "Mmm dd yyyy" , plus NULL at the end (12 char total) - Char String including length must be even*/
bool BOOT_CustomerBuildDateGet  (enum BOOT_IMAGE image, char *buildDateBuffer);

Step 4: Use these functions to access the data in the header, after the application image has been verified.

Reading the application header should only be done after the application image has been verified. Below, one of the values are read and if the value was found, the data will be processed.

        bool pass = BOOT_Customer16BitNumberGet(0, &number16Bit) ;

	if (pass) {
                /* All values read from FW files with no issues.  Now do something */
                /* with the values read      */ 
       }