Configuration Notes for AUTOSAR Bootloader (BL) Module

May 24, 2026 ยท View on GitHub

layout: post title: AUTOSAR Bootloader (BL) Configuration category: AUTOSAR comments: true

Configuration Notes for AUTOSAR Bootloader (BL) Module

Table of Contents

  1. Example Configuration
  2. General Configuration (general Section)
  3. Memory Layout (memory Section)
  4. Code Generation
  5. Signature Formats (V1/V2/V3)
  6. Windows Simulation Testing for CanBL

The Bootloader (BL) module manages application loading, validation, and A/B partition switching in AUTOSAR-compliant ECUs. This document outlines key configuration parameters, memory layout rules, and feature flags used during code generation.

1. Example Configuration

For a complete example, see:
Bootloader BL.json

This JSON file defines both general configurations and physical memory layout, which are consumed by the BL.py generator to produce BL_Cfg.h and BL_Cfg.c.

2. General Configuration (general Section)

The general section controls compile-time features and communication settings. All entries map directly to C preprocessor macros in BL_Cfg.h.

General Configuration

MacroTypeRequired?Description
BL_USE_ABbooleanOptionalEnable A/B dual-application partitioning.
BL_USE_AB_UPDATE_ACTIVEbooleanConditional(BL_USE_AB)Allow updating the currently active partition (use with caution).
BL_USE_METAbooleanOptionalEnable metadata (e.g., version, rolling counter) for application validation.
BL_USE_CRC_16booleanOptionalUse CRC16 for integrity checks during flashing or validation.
BL_USE_CRC_32booleanOptionalUse CRC32 for integrity checks during flashing or validation. Note: BL_USE_CRC_16 and BL_USE_CRC_32 cannot be enabled simultaneously, choose one.
BL_USE_AB_ACTIVE_BASED_ON_META_ROLLING_COUNTERbooleanConditional(BL_USE_AB andBL_USE_META)Select the active partition based on the metadata rolling counter (higher value = newer version).
BL_USE_APP_INFObooleanOptionalInclude basic application information section (e.g., build ID, timestamp).
BL_USE_APP_INFO_V2booleanConditional(BL_USE_APP_INFO)Use extended application info format (v2).
CAN_DIAG_P2P_RXhex stringOptionalCAN ID for point-to-point diagnostic request (e.g., "0x731").
CAN_DIAG_P2P_TXhex stringOptionalCAN ID for point-to-point diagnostic response.
CAN_DIAG_P2A_RXhex stringOptionalCAN ID for functional (point-to-all) diagnostic request.
DCM_DISABLE_PROGRAM_SESSION_PROTECTIONbooleanOptionalBypass security access requirement in programming session (for development only).
BL_USE_BUILTIN_FLS_READbooleanOptionalUse built-in flash read implementation instead of external service.
BL_USE_FLS_READbooleanOptionalEnable flash read service support (instead of direct memory access).
FINGER_PRINT_SIZEstringConditional(BL_USE_META)Size of the fingerprint region (e.g., "8*1024"). Evaluated at build time.
META_SIZEstringConditional(BL_USE_META)Size of the metadata region (e.g., "8*1024").
APP_SECINON_INFO_SIZEstringConditional(BL_USE_APP_INFO)Size of the application section info region (note: typo in name; kept for compatibility).
APP_VALID_FLAG_SIZEstringConditional(BL_USE_META)Size of the application validity flag region (e.g., "8*1024").
ROD_OFFSEThex stringOptionalOffset from application base address where RoD (Run-on-Demand) config is located.default: 0x800
FL_USE_WRITE_WINDOW_BUFFERbooleanOptionalEnable buffered flash write window for performance optimization.
FLASH_ERASE_SIZEintegerOptionalFlash sector erase size in bytes (e.g., 2048). Used for erase alignment. default: 512
FLASH_WRITE_SIZEintegerOptionalMinimum flash write alignment in bytes (e.g., 32). default: 8
FLASH_READ_SIZEintegerOptionalMinimum flash read alignment in bytes (e.g., 4). default: 1
FL_ERASE_PER_CYCLEintegerOptionalMaximum number of flash sectors erased per main function cycle (to limit execution time). Default behavior if omitted: erase one sector per cycle.
FL_WRITE_PER_CYCLEintegerOptionalMaximum number of flash write operations (of size FLASH_WRITE_SIZE) performed per main function cycle. Helps bound flash programming latency. default: 4096/FLASH_WRITE_SIZE.
FL_READ_PER_CYCLEintegerOptionalMaximum number of flash read units processed per cycle. default: 4096/FLASH_READ_SIZE.
FL_ERASE_RCRRP_CYCLEintegerOptionalMaximum number of erase main function cycles to return DCM_E_FORCE_RCRRP.Default: 0 - diabled.
FL_WRITE_RCRRP_CYCLEintegerOptionalMaximum number of write main function cycles to return DCM_E_FORCE_RCRRP.Default: 0 - diabled.
FL_WRITE_WINDOW_SIZEintegerConditional(FL_USE_WRITE_WINDOW_BUFFER)Size of the internal RAM buffer used for flash write aggregation, in bytes. Must be a multiple of FLASH_WRITE_SIZE. default: 8 * FLASH_WRITE_SIZE.
BL_APP_VALID_SAMPLE_SIZEintegerOptionalNumber of bytes read at each sampling point during application integrity validation. Default: aligned to 32 bytes.
BL_APP_VALID_SAMPLE_STRIDEintegerOptionalAddress increment (in bytes) between consecutive sampling points during CRC validation. Default: 1024.
BL_FLS_READ_SIZEintegerOptionalMaximum number of bytes read from flash in a single transfer (e.g., during DCM services). Default: 256.

? All boolean values generate #define MACRO when true. Numeric and string values are emitted as-is (e.g., #define FLASH_ERASE_SIZE 2048).

Notes on Required? Values:

  • Required: Must be present in BL.json; the generator assumes a default if missing, but best practice is to define explicitly.
  • Optional: Can be omitted; sensible defaults are used.
  • Conditional: Only needed when the referenced feature(s) are enabled.

3. Memory Layout (memory Section)

The memory section defines physical address ranges and attributes for bootloader components. Each flash bank is described with three key properties: address, size, and sectorSize.

Memory Region Attributes

AttributeTypeDescription
addresshex stringStart address of the memory region (e.g., "0xA0040000"). Must be aligned to flash page/sector boundaries.
sizestringSize of the region in bytes. May be a decimal number, hex literal (e.g., "0x10000"), or arithmetic expression (e.g., "0xA0300000-0xA0040000"). The generator evaluates expressions at build time.
sectorSizeintegerErase granularity of the flash device in bytes (e.g., 2048). Used internally for erase/write alignment and validation.

Defined Regions

RegionRequired?Description
FlashDriverYesMemory reserved for the flash driver (typically copied to RAM for execution). Contains low-level flash routines.
FlashAYesPrimary application partition. Always used.
FlashBConditionalSecondary application partition. Only used if BL_USE_AB is enabled.
FeeOptionalFlash EEPROM Emulation (FEE) storage area.

? Metadata Placement:
When BL_USE_META is enabled, metadata structures (fingerprint, meta, info, valid flag, backup) are placed in the last 2 sectors (generally) of each application region (FlashA/FlashB). The usable application space ends at (region_end - 2 sectors) to reserve space for these structures.

? Sector Alignment:
All flash operations respect sectorSize. The generator assumes that address and size are multiples of sectorSize.

4. Code Generation

The BL.py script reads BL.json and generates:

  • GEN/BL_Cfg.h: Contains all macros from the general section.
  • GEN/BL_Cfg.c: Defines memory layout arrays (blMemoryListA, blMemoryListB) and global symbol addresses (e.g., blAppMetaAddrA).

5. Signature Formats (V1/V2/V3)

The bootloader supports three signature formats for application integrity verification. These formats are implemented in tools/libraries/srec/srec.c and used by the Loader tool.

5.1 Format Comparison

FormatSign TypeCRC TypeDescriptionUse Case
V1crc16, crc32CRC16/CRC32Fixed-size padding with CRC at endLegacy, simple validation
V2crc16-v2, crc32-v2CRC16/CRC32Chained CRC with block metadataEnhanced integrity
V3crc16-v3, crc32-v3CRC16/CRC32Chained CRC with block list + magicRecommended for BL

5.2 V1 Format (crc16, crc32)

Algorithm:

  1. Pad the binary to a fixed total size with 0xFF
  2. Calculate CRC over the entire padded area (excluding CRC bytes)
  3. Append CRC value at the end (last 2 bytes for CRC16, 4 bytes for CRC32)

Memory Layout:

[Application Data][0xFF padding][CRC (2/4 bytes)]
^                              ^
startAddr                      startAddr + totalSize - crcLen

Loader Command:

Loader.exe -f app.s19 -s <total_size> -S crc32

5.3 V2 Format (crc16-v2, crc32-v2)

Algorithm:

  1. Calculate CRC incrementally over all S-record blocks (chained)
  2. Append metadata at the specified signature address containing:
    • Number of blocks (4 bytes)
    • CRC value (2 or 4 bytes)
    • Per-block info: address (4 bytes) + length (4 bytes) for each block

Memory Layout:

[Application Data]...[Signature Area]
                      ^
                 signAddr
                      [numOfBlks (4B)][CRC (2/4B)][block0_addr+len (8B)][block1_addr+len (8B)]...

Loader Command:

Loader.exe -f app.s19 -s <sign_address> -S crc32-v2

5.4 V3 Format (crc16-v3, crc32-v3)

Algorithm:

  1. Calculate CRC incrementally over all S-record blocks (chained)
  2. Append metadata after the last data block containing:
    • Per-block info: address (4 bytes) + length (4 bytes) for each block
    • Number of blocks (4 bytes)
    • CRC value (2 or 4 bytes)
    • Magic string "$BYASV3#" (8 bytes) for format identification

Memory Layout:

[Application Data]...[Block List][Footer]
                                   ^
                              signAddr (end of data)
                                   [block0_addr+len (8B)][block1_addr+len (8B)]...[numOfBlks (4B)][CRC (2/4B)][$BYASV3# (8B)]

Loader Command:

Loader.exe -f app.s19 -s <sign_address> -S crc32-v3

5.5 BL Integration

The bootloader's bl_core.c implements signature verification through the following functions:

FunctionPurpose
BL_CheckAppIntegrity()Validates application integrity on boot
BL_CheckIntegrity()Validates application via UDS request
getAppNSampledCrc()Computes sampled CRC for fast validation

V3 is the recommended format for the bootloader as it:

  • Supports multiple memory blocks (discontinuous regions)
  • Includes a magic string for format detection
  • Uses chained CRC calculation for better integrity
  • Enables the BL_USE_APP_INFO_V2 feature

5.7 BL_USE_APP_INFO vs BL_USE_APP_INFO_V2

The bootloader supports two configuration flags that determine how application metadata is handled:

BL_USE_APP_INFO (V2 Signature Format Support)

When BL_USE_APP_INFO is enabled:

  • Uses the application info section (blAppInfoAddr) to store section metadata
  • Metadata format: [numOfSections (4B)][CRC (4B)][section0_addr+len (8B)][section1_addr+len (8B)]...
  • Corresponds to the V2 signature format (crc32-v2)
  • The getAppNSampledCrc() function reads section info and validates CRC incrementally

BL_USE_APP_INFO_V2 (V3 Signature Format Support)

When BL_USE_APP_INFO_V2 is enabled:

  • Requires BL_USE_APP_INFO to be enabled
  • Detects and converts V3 signature format to V1-compatible format
  • Uses the BL_CopyAppInfoV2ForV1() function to:
    1. Locate the V3 footer with magic string "$BYASV3#"
    2. Copy the block list and footer to the app info address
    3. Enable backward compatibility with V2 validation logic
  • Corresponds to the V3 signature format (crc32-v3)

Key Differences

FeatureBL_USE_APP_INFOBL_USE_APP_INFO_V2
Signature FormatV2 (crc32-v2)V3 (crc32-v3)
Magic StringNone"$BYASV3#"
Metadata LocationFixed app info addressEnd of application data
Conversion RequiredNoYes (V3 to V1 format)
Block List OrderHeader then CRC then BlocksBlocks then Header/CRC then Magic

Format Conversion (BL_CopyAppInfoV2ForV1)

The BL_CopyAppInfoV2ForV1() function performs the following steps:

V3 Format (end of application):
[Application Data]...[Block List][numOfBlks (4B)][CRC (4B)][$BYASV3# (8B)]

      <--> BL_CopyAppInfoV2ForV1()

V1 Format (at blAppInfoAddr):
[numOfBlks (4B)][CRC (4B)][Block List]

This conversion allows the bootloader to use the same validation logic for both V2 and V3 formats.

Use CaseRecommended FlagsSignature Format
Simple single-block appsNonecrc32 (V1)
Multi-block appsBL_USE_APP_INFOcrc32-v2 (V2)
Advanced multi-block + format detectionBL_USE_APP_INFO + BL_USE_APP_INFO_V2crc32-v3 (V3)

5.7 Signature Type Mapping

The Loader tool uses the -S parameter to select the signature algorithm:

ParameterSign TypeCRC Initial Value
crc16SREC_SIGN_CRC160xFFFF
crc32SREC_SIGN_CRC320xFFFFFFFF
crc16-v2SREC_SIGN_CRC16_V20xFFFF
crc32-v2SREC_SIGN_CRC32_V20xFFFFFFFF
crc16-v3SREC_SIGN_CRC16_V30xFFFF
crc32-v3SREC_SIGN_CRC32_V30xFFFFFFFF

Note: V2 and V3 use chained CRC calculation (passing previous CRC as initial value), while V1 uses a single CRC calculation over the entire padded region.

6. Windows Simulation Testing for CanBL

When testing CanBL on Windows using simulation, you need to generate dummy flash driver and application files, then sign them with the Loader tool before testing.

6.1 Prerequisites

Ensure the following tools are available in your PATH:

  • objcopy (from MSYS2 binutils package)
  • Loader.exe (built from --app=Loader)

6.2 Build Required Components

First, build the loader and related libraries:

scons --lib=AsOne
scons --lib=LoaderFBL
scons --app=IsoTpSend
scons --app=Loader
scons --app=CanBL
scons --app=CanApp

6.3 Generate Dummy Flash Driver (1052 bytes)

Use MSYS objcopy to create a dummy flash driver file with sequential values (0, 1, 2, ..., 255, 0, 1, ...) at address 0, placed in the CanBL build folder:

# Create a file with 1052 bytes of sequential values (0, 1, 2, ..., 255, 0, 1, ...) using Python
python -c "with open('build/FlashDriverDummy.bin', 'wb') as f: f.write(bytes([i % 256 for i in range(1052)]))"

# Convert to S19 format using MSYS objcopy with address at 0
objcopy -I binary -O srec --adjust-vma 0 build/FlashDriverDummy.bin build/FlashDriverDummy.s19

6.4 Generate Dummy Application (Multi-Section)

Save the following Python script as build/gensims19.py and run it to generate multi-section S19 files:

#!/usr/bin/env python3
import argparse

def make_s19_record(addr, chunk):
    addr_bytes = [(addr >> 24) & 0xFF, (addr >> 16) & 0xFF, (addr >> 8) & 0xFF, addr & 0xFF]
    count = len(chunk) + 5
    body = [count] + addr_bytes + list(chunk)
    checksum = (~sum(body)) & 0xFF
    line = 'S3' + ''.join('%02X' % b for b in body) + '%02X\n' % checksum
    return line

def main():
    parser = argparse.ArgumentParser(description='Generate multi-section S19 dummy application')
    parser.add_argument('-n', '--sections', type=eval, default=8, help='Number of sections (default: 8)')
    parser.add_argument('-s', '--section-size', type=eval, default=4096, help='Size of each section in bytes (default: 4096)')
    parser.add_argument('-g', '--gap', type=eval, default=1024, help='Gap between sections in bytes (default: 1024)')
    parser.add_argument('-b', '--base', type=eval, default=0x1000, help='Base address (default: 0x1000)')
    parser.add_argument('-o', '--output', default='build/AppDummy.s19', help='Output file (default: build/AppDummy.s19)')
    args = parser.parse_args()

    data = bytes([i % 256 for i in range(args.section_size * args.sections)])

    with open(args.output, 'w') as f:
        f.write('S00600004844521B\n')
        addr = args.base
        for sec in range(args.sections):
            for offset in range(0, args.section_size, 16):
                chunk = data[sec * args.section_size + offset : sec * args.section_size + offset + 16]
                if len(chunk) > 0:
                    f.write(make_s19_record(addr, chunk))
                    addr += len(chunk)
            addr += args.gap
        f.write('S5030001FB\n')
        f.write('S9030001FB\n')

    print('Generated %s with %d sections' % (args.output, args.sections))

if __name__ == '__main__':
    main()

Run without arguments (uses defaults):

python build/gensims19.py

Generate separate files for partition A and B:

# Generate for partition A
python build/gensims19.py -n 8 -s 8192 -g 2048 -b 0x1000 -o build/AppDummy.s19.A

# Generate for partition B
python build/gensims19.py -n 8 -s 8192 -g 2048 -b 0x100000 -o build/AppDummy.s19.B

6.5 Sign Application with Loader

Sign the application using the Loader tool:

# Sign for partition A
build\nt\GCC\Loader\Loader.exe -f build/AppDummy.s19.A -s 0xfff00 -S crc32-v3

# Sign for partition B
build\nt\GCC\Loader\Loader.exe -f build/AppDummy.s19.B -s 0x1fff00 -S crc32-v3

# Sign for FlashDriver
build\nt\GCC\Loader\Loader.exe -f build/FlashDriverDummy.s19 -s 2048 -S crc32

6.6 Test Application Programming

Use the Loader tool to program the signed application to CanBL:

# start the CAN bootloader
build\nt\GCC\CanBL\CanBL.exe

build\nt\GCC\Loader\Loader.exe -l 64 -c FBL -S crc32 -f build/FlashDriverDummy.s19.sign -a build/AppDummy.s19.A.sign

build\nt\GCC\Loader\Loader.exe -l 64 -c FBL -S crc32 -f build/FlashDriverDummy.s19.sign -a build/AppDummy.s19.B.sign