LibXR::STM32Flash Class Reference

STM32 闪存驱动实现 / STM32 flash driver implementation. More...

#include <stm32_flash.hpp>

Inheritance diagram for LibXR::STM32Flash:

Collaboration diagram for LibXR::STM32Flash:

Public Member Functions
	STM32Flash (const FlashRegion *regions, size_t region_count, uint32_t start_address)
	构造闪存对象 / Construct flash object
	STM32Flash (const FlashRegion *regions, size_t region_count)
	用末尾两个扇区构造，供 DatabaseRaw 的主块和备份块使用 / Construct with the last two sectors, for the main and backup blocks of DatabaseRaw
ErrorCode	Erase (size_t offset, size_t size) override
	擦除闪存的指定区域 / Erases a section of the flash memory.
ErrorCode	Write (size_t offset, ConstRawData data) override
	向闪存写入数据 / Writes data to the flash memory.
Public Member Functions inherited from LibXR::Flash
	Flash (size_t min_erase_size, size_t min_write_size, RawData flash_area)
	构造函数，初始化闪存属性。 Constructs a Flash object with specified properties.
virtual ErrorCode	Read (size_t offset, RawData data)
	从闪存中读取数据 / Reads data from the flash memory.
size_t	MinEraseSize () const
	获取最小可擦除块大小（字节）。 Returns the minimum erasable block size in bytes.
size_t	MinWriteSize () const
	获取最小可写块大小（字节） / Returns the minimum writable block size in bytes.
size_t	Size () const
	获取闪存存储区域的大小 / Returns the size of the flash memory area.

Static Public Attributes
static constexpr size_t	MIN_WRITE_SIZE = STM32FlashMinWriteSize()
	最小写入单位（字节），由 HAL 的 FLASH_TYPEPROGRAM_* 宏确定；可直接作为 DatabaseRaw 的模板参数 / Minimum write unit in bytes, determined from the HAL FLASH_TYPEPROGRAM_* macros; usable directly as the DatabaseRaw template argument

Detailed Description

STM32 闪存驱动实现 / STM32 flash driver implementation.

Precondition

擦写调用及相关缓存控制由调用方串行化；等待期间 HAL tick 必须能推进。 The caller serializes erase/program calls and related cache control; the HAL tick must advance during waits.

Note

擦写期间暂时关闭相关缓存；进入擦写流程后，成功或失败返回均恢复缓存开关并锁定 Flash。 Related caches are temporarily disabled during erase/program operations. Once the operation starts, success and failure returns restore the original cache enable state and lock Flash.

扇区表须从 Flash 起始地址开始，按地址用若干段列出整片 Flash 的扇区或页；一段可以 跨 bank。擦除时按地址判断所在 bank，H5、H7 和使用 Page 字段的系列按 bank 内序号擦除， F2/F4/F7 按跨 bank 的扇区号擦除。不支持 bank 交换（SWAP_BANK、BFB2 等选项字节）。 The sector table must list the sectors or pages of the whole Flash in address order as runs, starting at the Flash base; a run may cross a bank boundary. Erase takes the bank from the address; H5, H7 and the families with a Page field erase by the number within the bank, F2/F4/F7 by the sector number across both banks. Bank swap (SWAP_BANK, BFB2 and similar option bytes) is not supported.

Definition at line 137 of file stm32_flash.hpp.

Constructor & Destructor Documentation

STM32Flash() [1/2]

STM32Flash::STM32Flash	(	const FlashRegion *	regions,
		size_t	region_count,
		uint32_t	start_address )

构造闪存对象 / Construct flash object

Parameters

regions	扇区表 / Sector table
region_count	扇区表的段数 / Number of runs in the sector table
start_address	存储区的起始地址，须正好是某个扇区的起点；存储区一直到 Flash 末尾 / Start address of the storage area; must be exactly the start of a sector; the area extends to the end of the Flash

Definition at line 123 of file stm32_flash.cpp.

    : Flash(SectorSizeAt(regions, region_count, start_address), MIN_WRITE_SIZE,
            {reinterpret_cast<void*>(start_address),
             TableEnd(regions, region_count) - start_address}),
      regions_(regions),
      base_address_(start_address),
      program_type_(DetermineProgramType()),
      region_count_(region_count)
{
}

STM32Flash() [2/2]

STM32Flash::STM32Flash	(	const FlashRegion *	regions,
		size_t	region_count )

用末尾两个扇区构造，供 DatabaseRaw 的主块和备份块使用 / Construct with the last two sectors, for the main and backup blocks of DatabaseRaw

Parameters

regions	扇区表 / Sector table
region_count	扇区表的段数 / Number of runs in the sector table

Definition at line 135 of file stm32_flash.cpp.

    : STM32Flash(regions, region_count, SecondToLastSector(regions, region_count))
{
}

Member Function Documentation

Erase()

ErrorCode STM32Flash::Erase ( size_t offset, size_t size )

overridevirtual

擦除闪存的指定区域 / Erases a section of the flash memory.

Parameters

offset	要擦除的起始偏移地址 / The starting offset of the section to erase.
size	要擦除的区域大小 / The size of the section to erase.

Returns

返回操作结果的错误码 / ErrorCode indicating success or failure.

Implements LibXR::Flash.

Definition at line 140 of file stm32_flash.cpp.

{
  if (size == 0)
  {
    return ErrorCode::ARG_ERR;
  }
 
  uint32_t start_addr = base_address_ + offset;
  uint32_t end_addr = start_addr + size;
 
  FlashOperationGuard operation;
 
  // 表按地址排列；index 是跨段的扇区序号，bank_entries 记录每个 bank 中已经走过的扇区
  // 数，即下一个扇区在该 bank 内的序号。bank 2 的起点由表给出，小容量型号上它与 bank 1
  // 之间可能有空洞（如 H743xG 在 0x08100000，G474xC 在 0x08040000）。
  // The table is ordered by address; index is the sector number across runs, and
  // bank_entries counts the sectors already passed in each bank, which is the next
  // sector's number within that bank. The table gives where bank 2 starts, after a gap on
  // smaller parts (H743xG at 0x08100000, G474xC at 0x08040000).
  uint32_t bank_entries[2] = {0U, 0U};
  [[maybe_unused]] uint32_t index = 0U;
  for (size_t r = 0; r < region_count_; ++r)
  {
    const auto& region = regions_[r];
    for (uint32_t k = 0; k < region.sector_count; ++k, ++index)
    {
      const uint32_t address = region.address + region.sector_size * k;
#if defined(FLASH_BANK_2)
      const size_t bank_slot = (STM32FlashBankOf(address) == FLASH_BANK_2) ? 1U : 0U;
#else
      const size_t bank_slot = 0U;
#endif
      [[maybe_unused]] const uint32_t number_in_bank = bank_entries[bank_slot]++;
      if (address + region.sector_size <= start_addr)
      {
        continue;
      }
      if (address >= end_addr)
      {
        return ErrorCode::OK;
      }
      FLASH_EraseInitTypeDef erase_init = {};
 
#if defined(FLASH_TYPEERASE_PAGES) && defined(FLASH_PAGE_SIZE)  // STM32F1/G4... series
      // 有 Page 字段的系列（G0、G4、L4、L5、U5 等）按 bank 内页号编号；其余系列用页地址。
      // Families with a Page field (G0, G4, L4, L5, U5, ...) number pages within each
      // bank; the others take the page address.
      erase_init.TypeErase = FLASH_TYPEERASE_PAGES;
      SetNbPages(erase_init, address, number_in_bank);
      erase_init.NbPages = 1;
      SetBanks(erase_init, address);
#elif defined(FLASH_TYPEERASE_SECTORS)  // STM32F4/F7/H7... series
      erase_init.TypeErase = FLASH_TYPEERASE_SECTORS;
#if defined(FLASH_SECTOR_SIZE)
      // H5、H7 的扇区大小一致，按 bank 内扇区号编号。
      // H5 and H7 have uniform sectors numbered within each bank.
      erase_init.Sector = number_in_bank;
#elif defined(FLASH_SECTOR_TOTAL)
      // F2、F4、F7 的扇区号跨两个 bank 连续编号，等于跨段的扇区序号。
      // F2, F4 and F7 number sectors across both banks, as the index across runs does.
      erase_init.Sector = index;
#else
#error "No supported Flash sector numbering defined"
#endif
      erase_init.NbSectors = 1;
#if defined(FLASH_BANK_1)
      erase_init.Banks = STM32FlashBankOf(address);
#endif
#if defined(FLASH_CR_PSIZE)
      erase_init.VoltageRange = FLASH_VOLTAGE_RANGE_1;
#endif
#else
      return ErrorCode::NOT_SUPPORT;
#endif
 
      uint32_t error = 0;
      HAL_StatusTypeDef status = HAL_FLASHEx_Erase(&erase_init, &error);
      if (status != HAL_OK || error != 0xFFFFFFFFU)
      {
        return ErrorCode::FAILED;
      }
    }
  }
 
  return ErrorCode::OK;
}

Write()

ErrorCode STM32Flash::Write ( size_t offset, ConstRawData data )

overridevirtual

向闪存写入数据 / Writes data to the flash memory.

Parameters

offset	数据写入的起始偏移地址 / The starting offset to write data.
data	需要写入的数据 / The data to be written.

Returns

返回操作结果的错误码 / ErrorCode indicating success or failure.

Implements LibXR::Flash.

Definition at line 227 of file stm32_flash.cpp.

{
  if (!data.addr_ || data.size_ == 0)
  {
    return ErrorCode::ARG_ERR;
  }
 
  uint32_t addr = base_address_ + offset;
  if (!IsInRange(addr, data.size_))
  {
    return ErrorCode::OUT_OF_RANGE;
  }
 
  FlashOperationGuard operation;
 
  const uint8_t* src = reinterpret_cast<const uint8_t*>(data.addr_);
  size_t written = 0;
 
#if defined(FLASH_TYPEPROGRAM_FLASHWORD) || defined(FLASH_TYPEPROGRAM_QUADWORD)
  alignas(LibXR::HW_CACHE_LINE_SIZE)
      uint32_t flash_word_buffer[MIN_WRITE_SIZE / sizeof(uint32_t)];
  while (written < data.size_)
  {
    size_t chunk_size = LibXR::min<size_t>(MinWriteSize(), data.size_ - written);
 
    Memory::FastSet(flash_word_buffer, 0xFF, sizeof(flash_word_buffer));
    Memory::FastCopy(flash_word_buffer, src + written, chunk_size);
 
    if (Memory::FastCmp(reinterpret_cast<const uint8_t*>(addr + written), src + written,
                        chunk_size) == 0)
    {
      written += chunk_size;
      continue;
    }
 
    if (HAL_FLASH_Program(program_type_, addr + written,
                          reinterpret_cast<uint32_t>(flash_word_buffer)) != HAL_OK)
    {
      return ErrorCode::FAILED;
    }
 
    written += chunk_size;
  }
 
#else
  while (written < data.size_)
  {
    size_t chunk_size = LibXR::min<size_t>(MinWriteSize(), data.size_ - written);
 
    if (Memory::FastCmp(reinterpret_cast<const uint8_t*>(addr + written), src + written,
                        chunk_size) == 0)
    {
      written += chunk_size;
      continue;
    }
 
    uint64_t word = 0xFFFFFFFFFFFFFFFF;
    Memory::FastCopy(&word, src + written, chunk_size);
 
    if (HAL_FLASH_Program(program_type_, addr + written, word) != HAL_OK)
    {
      return ErrorCode::FAILED;
    }
 
    written += chunk_size;
  }
#endif
 
  return ErrorCode::OK;
}

Member Data Documentation

MIN_WRITE_SIZE

size_t LibXR::STM32Flash::MIN_WRITE_SIZE = STM32FlashMinWriteSize()

staticconstexpr

最小写入单位（字节），由 HAL 的 FLASH_TYPEPROGRAM_* 宏确定；可直接作为 DatabaseRaw 的模板参数 / Minimum write unit in bytes, determined from the HAL FLASH_TYPEPROGRAM_* macros; usable directly as the DatabaseRaw template argument

Definition at line 146 of file stm32_flash.hpp.

---

The documentation for this class was generated from the following files:

• driver/st/stm32_flash.hpp
• driver/st/stm32_flash.cpp