Skip to main content

Flash Database

After code generation, a file named User/flash_map.hpp will be created. This file defines the STM32 flash sector layout. Each entry is a run of adjacent sectors of equal size: start address, sector size in bytes and sector count. The format is similar to:

#pragma once
// Generated by `libxr gen`; do not edit by hand.
// MCU: STM32F407IGH6

#include "main.h"
#include "stm32_flash.hpp"

constexpr LibXR::FlashRegion FLASH_REGIONS[] = {
    {0x08000000, 0x00004000, 4},
    {0x08010000, 0x00010000, 1},
    {0x08020000, 0x00020000, 7},
};

constexpr size_t FLASH_REGION_NUMBER = sizeof(FLASH_REGIONS) / sizeof(LibXR::FlashRegion);

libxr stm32 flash-info <model> prints the layout of a model on its own. app_main.cpp includes flash_map.hpp only when database.enable is true or the User Code uses FLASH_REGIONS or FLASH_REGION_NUMBER. When no flash layout can be derived for the MCU, libxr gen logs a warning, generates no flash_map.hpp, and deletes a previously generated flash_map.hpp.

Generated from libxr_config.yaml​

With database.enable set to true in User/libxr_config.yaml, libxr gen generates the Flash object and the database object in app_main(), and the database uses the last two sectors of the Flash; generated with --xrobot, the database is registered as database of type LibXR::Database:

database:
  enable: true
  block_size: auto
  // Flash and database
  static STM32Flash flash(FLASH_REGIONS, FLASH_REGION_NUMBER);
  static DatabaseRaw<STM32Flash::MIN_WRITE_SIZE> database(flash);

block_size gives the template argument of DatabaseRaw, the minimum write unit of the database in bytes, which must not be smaller than the minimum write unit of the Flash. The default auto generates STM32Flash::MIN_WRITE_SIZE, the minimum write unit of the Flash that LibXR derives from the HAL of the chip, such as 1 on F4, 2 on F1, 8 on G4 and 32 on H723; a positive integer is used as it is, e.g. block_size: 32 generates DatabaseRaw<32>. Any other value stops the generation, e.g. block_size: wide:

$ libxr gen -i .config.yaml -o User/app_main.cpp
[INFO] System: FreeRTOS
[ERROR] Generation failed: User\libxr_config.yaml: database.block_size 'wide' is not auto or a positive integer

Creating the Objects in User Code​

With database.enable set to false, the two objects can also be created in the User Code, written as in the generated code above; the third argument of STM32Flash can give the start address of the database storage area, which must be exactly the start of a sector and extends to the end of the Flash; without it the last two sectors are used (0x080C0000 in the STM32F407IGH6 layout at the top). Keys and how to read and write them (Database::Key, Set()), DatabaseRawSequential and the recycle threshold are described in the middleware page Flash Database.

Hand-written flash and database objects cannot be used together with database.enable: true: app_main() then already has the generated static STM32Flash flash and static DatabaseRaw<...> database, and objects of the same names in User Code 2 or 3 are in the same scope, which fails to compile as a redefinition.

When the User Code uses FLASH_REGIONS, app_main.cpp includes flash_map.hpp from the next generation on; to compile before that, write #include "flash_map.hpp" in User Code 1.