1.14 Bootloader Linker and Build Options

Compiler, Linker and Post Build Options for the Bootloader and Application Projects

Since the bootloader often requires specialized build features, extra build options are often required. These settings are automatically enabled in the most recent versions of MPLABx.

Basic Verification Linker Settings

If the user is not enabling any Code Protect or Codeguard settings, then no linker command line changes are required and the user can skip to the Application Post Build Options below

Code Protect / Code Guard settings

When the user selected Code Protect Bootloader, the device is configured to use Codeguard. This feature requires special linker options to place the code in the correct place. The three added features are listed below along with the command line that needs to be added to the project

Bootloader Project Linker Settings

–add-flags-code=boot Forces all code in this project placed in the boot section.
–add-flags-const=boot Forces all constants in this project placed in the boot section.
-D__USE_BFA Allows the boot section to be placed according to the security mode and not default to normal system map.

–add-flags-code=boot,–add-flags-const=boot,-D__USE_BFA

This linker command should automatically be added to the project for the user. However, they can be added manually by following the below steps.

Go to Project Properties
Go to XC16->xc16-ld
Under additional options add the following: –add-flags-code=boot,–add-flags-const=boot,-D__USE_BFA

ECDSA Verification with Code Protect / Code Guard settings

When the user selected Code Protect Bootloader, the device is configured to use Codeguard. This feature requires special linker options to place the code in the correct place. Below are the linker settings for the bootloader.

Bootloader Project Linker Settings

–add-flags-code=boot,–add-flags-const=boot,-D__USE_BFA

The steps needed to change this are shown below.

Goto Project Properties
Goto XC16->xc16-ld
Under additional options add the following: –add-flags-code=boot,–add-flags-const=boot,-D__USE_BFA

Application Project Post Build Settings

As the final part of the build process, the application code needs to be signed and converted to a hex format to download. This process is the same for all verification methods and is shown below.

Windows Post Build Command

cd mcc_generated_files/boot && postBuild.bat $(MP_CC_DIR) $(ProjectDir) $(ImageDir) $(ImageName) $(IsDebug)

Linux Post Build Command

cd mcc_generated_files/boot && ./postBuild.sh $(MP_CC_DIR) $(ProjectDir) $(ImageDir) $(ImageName) $(IsDebug)

Adding Post Build step to Application Project

Go to Project Properties
Select the 'Building' left navigation node.
Check the box next to 'Execute this line after the build'.

In the text field below add:

Windows machine

cd mcc_generated_files/boot && postBuild.bat $(MP_CC_DIR) $(ProjectDir) $(ImageDir) $(ImageName) $(IsDebug)

Linux/Unix/Mac machine

cd mcc_generated_files/boot && ./postBuild.sh $(MP_CC_DIR) $(ProjectDir) $(ImageDir) $(ImageName) $(IsDebug)

Application Side Linker Workaround

Due to XC16-2324 and XC16-2333, it is possible for link-time or run-time issues in specific situations when using this bootloader solution. The following workarounds are required on the application side only when the project has the all of the following settings:

Device > 64KB
Code Protect / Code Guard enabled
XC-16 (any version) or XC-DSC 3.00

Workaround #1 (Recommended): Update to XC-DSC 3.10 or newer. It is recommended to update to the latest compiler when possible.

Workaround #2: When it is not possible to update the version of the compiler in use for the project, the following manual workaround will resolve this potential issue.

Copy the device linker file into the project. The location of the golden linker file on the system depends on the compiler versions and Device Family Packs (DFPs) installed. The easiest way to find the most current linker file is to first build the project with the default settings. At the very end of the build process in the Output window, there will be a line that shows the linker file used for the build as show below. Copy this linker file and place in the root of the project folder.
- "Info: Loading file: <FILE PATH>/gld/<device_name>.gld”
Modify the linker file. Open the copied version of the linker file in a text/code editor. Locate the first SECTIONS declaration and add the following line inside of the SECTIONS{} declaration at the top.
```
.application_header 0x<BOOT_CONFIG_APPLICATION_IMAGE_APPLICATION_HEADER_ADDRESS>: { KEEP(*(.application_header)); } >program
```
NOTE: Replace BOOT_CONFIG_APPLICATION_IMAGE_APPLICATION_HEADER_ADDRESS with the resolved value defined in boot_config.h. These instructions and the exact line to copy with the resolved value already injected can be found in application_header.S in 16-bit Bootloader version 1.25.1 and later.
When complete, it should look similar to the following:
```
SECTIONS
    {
        .application_header 0x<BOOT_CONFIG_APPLICATION_IMAGE_APPLICATION_HEADER_ADDRESS>: { KEEP(*(.application_header)); } >program

    #if !defined(__CORESIDENT) || defined(__DEFINE_RESET)
        .reset :
        {
            SHORT(ABSOLUTE(__reset));
            SHORT(0x04);
            SHORT((ABSOLUTE(__reset) >> 16) & 0x7F);
            SHORT(0);
        } >reset
    #endif
```
Save the modified linker file.
Add the modified linker file to the project. In the "Projects" pane in MPLAB X, right click on the "Linker Files" folder. Select "Add Existing Item" Browse to the modified linker file modified in step 2.