Bootloader Core
Bootloader

Core bootloader functionality. More...

Collaboration diagram for Bootloader Core:

## Data Structures

union | standard_version_t
| Structure of version property. More...
struct | standard_version_t.__unnamed__
struct | standard_version_t.B

## Enumerations

enum | shutdown_type_t { kShutdownType_Shutdown = 0, kShutdownType_Cleanup = 1, kShutdownType_Reset = 2 }
| Shutdown types.

enum

_bootloader_status {
kStatus_UnknownCommand = MAKE_STATUS(kStatusGroup_Bootloader, 0),
kStatus_SecurityViolation = MAKE_STATUS(kStatusGroup_Bootloader, 1),
kStatus_AbortDataPhase = MAKE_STATUS(kStatusGroup_Bootloader, 2),
kStatus_Ping = MAKE_STATUS(kStatusGroup_Bootloader, 3),
kStatus_NoResponse = MAKE_STATUS(kStatusGroup_Bootloader, 4),
kStatus_NoResponseExpected = MAKE_STATUS(kStatusGroup_Bootloader, 5)
}

| Bootloader status codes.
enum | _bl_status_groups { kStatusGroup_Bootloader = kStatusGroup_ApplicationRangeStart, kStatusGroup_SBLoader, kStatusGroup_MemoryInterface, kStatusGroup_PropertyStore, kStatusGroup_AppCrcCheck, kStatusGroup_Packetizer, kStatusGroup_ReliableUpdate }
| Bootloader status group numbers. More...
enum | _bl_driver_status_groups { kStatusGroup_QuadSPIDriver = 4, kStatusGroup_OTFADDriver = 5 }
| Driver status group numbers. More...
enum | _external_mem_identifiers { kExternalMemId_QuadSPI0 = 1 }
| External memory identifiers. More...

## Functions

void | shutdown_cleanup (shutdown_type_t shutdown)
| Prepare system for exiting the bootloader. More...
bool | is_valid_application_location (uint32_t applicationAddress)
| Verify that a given address is ok to jump to. More...
static const char * | get_peripheral_name (uint32_t peripheralTypeMask)
| Returns the name of a peripheral given its type mask.
static void | get_user_application_entry (uint32_t *appEntry, uint32_t *appStack)
| Returns the user application address and stack pointer. More...
static void | jump_to_application (uint32_t applicationAddress, uint32_t stackPointer)
| Exits bootloader and jumps to the user application.
static bool | is_direct_boot (void)
static peripheral_descriptor_t const * | get_active_peripheral (void)
| Determines the active peripheral. More...
static void | bootloader_init (void)
| Initialize the bootloader and peripherals. More...
static void | bootloader_run (void)
| Bootloader outer loop. More...
static void | bootloader_flash_init (void)
static void | configure_quadspi_as_needed (void)
int | main (void)
| Entry point for the bootloader.
static bool | is_application_ready_for_executing (uint32_t applicationAddress)
| Jump application is considered ready for executing if the location is valid and crc check is passed.
void | exit (int arg)

## Variables

static const char *const | kPeripheralNames []

## Usage Information

Core bootloader functionality.

## Data Structure Documentation

union standard_version_t

Structure of version property.

### Public Member Functions

| StandardVersion ()
| StandardVersion (uint32_t version)

### Data Fields

struct {
uint8_t | bugfix
| bugfix version [7:0]
uint8_t | minor
| minor version [15:8]
uint8_t | major
| major version [23:16]
char | name
| name [31:24]
}; |
uint32_t | version
| combined version numbers
struct {
uint32_t | bugfix: 8
| bugfix version [7:0]
uint32_t | minor: 8
| minor version [15:8]
uint32_t | major: 8
| major version [23:16]
uint32_t | name: 8
| name [31:24]
} | B
struct {
uint32_t | bugfix: 8
| bugfix version [7:0]
uint32_t | minor: 8
| minor version [15:8]
uint32_t | major: 8
| major version [23:16]
uint32_t | name: 8
| name [31:24]
} | B

struct standard_version_t.__unnamed__

Data Fields
uint8_t | bugfix | bugfix version [7:0]
uint8_t | major | major version [23:16]
uint8_t | minor | minor version [15:8]
char | name | name [31:24]

struct standard_version_t.B

Data Fields
uint32_t | bugfix: 8 | bugfix version [7:0]
uint32_t | major: 8 | major version [23:16]
uint32_t | minor: 8 | minor version [15:8]
uint32_t | name: 8 | name [31:24]

## Enumeration Type Documentation

enum _bl_driver_status_groups

Driver status group numbers.

Enumerator
kStatusGroup_QuadSPIDriver | QSPI driver status group number.
kStatusGroup_OTFADDriver | OTFAD driver status group number.

enum _bl_status_groups

Bootloader status group numbers.

Enumerator
kStatusGroup_Bootloader | Bootloader status group number (100).
kStatusGroup_SBLoader | SB loader status group number (101).
kStatusGroup_MemoryInterface | Memory interface status group number (102).
kStatusGroup_PropertyStore | Property store status group number (103).
kStatusGroup_AppCrcCheck | Application crc check status group number (104).
kStatusGroup_Packetizer | Packetizer status group number (105).
kStatusGroup_ReliableUpdate | Reliable Update status groupt number (106).

enum _external_mem_identifiers

External memory identifiers.

## Function Documentation

static void bootloader_flash_init | ( | void |  | ) |

static

A static buffer used to hold flash_run_command()

A static buffer used to hold flash_cache_clear_command()

static void bootloader_init | ( | void |  | ) |

static

Initialize the bootloader and peripherals.

This function initializes hardware and clocks, loads user configuration data, and initialzes a number of drivers. It then enters the active peripheral detection phase by calling get_active_peripheral(). Once the peripheral is detected, the packet and comand interfaces are initialized.

Note that this routine may not return if peripheral detection times out and the bootloader jumps directly to the user application in flash.

static void bootloader_run | ( | void |  | ) |

static

Bootloader outer loop.

Infinitely calls the command interface and active peripheral control interface pump routines.

void exit | ( | int | arg | ) |

Since we never exit this gets rid of the C standard functions that cause extra ROM size usage.

static peripheral_descriptor_t const * get_active_peripheral | ( | void |  | ) |

static

Determines the active peripheral.

This function has several stages:

- Init enabled peripherals.
- Compute timeout.
- Wait for peripheral activity with timeout.
- Shutdown inactive peripherals.

If peripheral detection times out, then this function will call jump_to_application() to directly enter the user application.

The timeout value comes from the BCA if set, or the #BL_DEFAULT_PERIPHERAL_DETECT_TIMEOUT configuration macro. If the boot pin is asserted, or if there is not a valid user application in flash, then the timeout is disabled and peripheral detection will continue infinitely.

static void get_user_application_entry | ( | uint32_t * | appEntry,
|  | uint32_t * | appStack
| ) |  |

static

Returns the user application address and stack pointer.

For flash-resident and rom-resident target, gets the user application address and stack pointer from the APP_VECTOR_TABLE. Ram-resident version does not support jumping to application address.

bool is_valid_application_location | ( | uint32_t | applicationAddress | ) |

Verify that a given address is ok to jump to.

Parameters

  applicationAddress | The entry point address to validate.

Returns
  Boolean indicating whether the address is valid.

A given jump address is considered valid if:

- Not 0x00000000
- Not 0xffffffff
- Not the reset handler entry point for the bootloader
- Is in flash or is in RAM or QuadSPI (if available)
  Note
    this interface is also used by the configure_quadspi command

void shutdown_cleanup | ( | shutdown_type_t | shutdown | ) |

Prepare system for exiting the bootloader.

Performs any cleanup necessary to restore the system to default state prior to exiting the bootloader. This involves restoring the vector table to default, managing the flash cache, and so on.

This routine must be invoked prior to permanently exiting the bootloader.

Parameters

  shutdown | Specifies different uses for this function 'kShutdownType_Shutdown' means clean up prior to permanently exiting the bootloader. 'kShutdownType_Cleanup' means only clear (flush) the flash cache 'kShutdownType_Reset' means only shutdown all peripherals.

## Variable Documentation

const char* const kPeripheralNames[]

static

Initial value:
= {
"UART",
"I2C",
"SPI",
"CAN",
"HID",
"CDC",
"DFU",
"MSD"
}