适用于不支持逆序写入的 Flash 存储的数据库实现 (Database implementation for Flash storage that does not support reverse writing). More...

#include <raw_sequential.hpp>

Inheritance diagram for LibXR::DatabaseRawSequential:

Collaboration diagram for LibXR::DatabaseRawSequential:

Data Structures
struct	FlashInfo
	Flash 存储的块信息结构 (Structure representing a Flash storage block). More...

struct	KeyInfo
	键信息结构，存储键的元数据 (Structure containing key metadata). More...

Public Member Functions
	DatabaseRawSequential (Flash &flash, size_t max_buffer_size=256)
	构造函数，初始化 Flash 存储和缓冲区 (Constructor initializing Flash storage and buffer).

void	Init ()
	初始化数据库存储区，确保主备块正确 (Initialize database storage, ensuring main and backup blocks are valid).

void	Save ()
	保存当前缓冲区内容到 Flash (Save the current buffer content to Flash).

void	Load ()
	从 Flash 加载数据到缓冲区 (Load data from Flash into the buffer).

void	Restore ()
	还原存储数据，清空 Flash 区域 (Restore storage data, clearing Flash memory area).

ErrorCode	Get (Database::KeyBase &key) override
	获取数据库中的键值 (Retrieve the key's value from the database).

ErrorCode	Set (KeyBase &key, RawData data) override
	设置数据库中的键值 (Set the key's value in the database).

ErrorCode	Add (KeyBase &key) override
	添加新键到数据库 (Add a new key to the database).

Private Types
enum class	BlockType : uint8_t { MAIN = 0 , BACKUP = 1 }
	存储块类型 (Storage block type). More...

Private Member Functions
ErrorCode	AddKey (const char name, const void data, size_t size)

ErrorCode	SetKey (const char name, const void data, size_t size)

ErrorCode	SetKey (size_t offset, const void *data, size_t size)

ErrorCode	GetKeyData (size_t offset, RawData data)

void	InitBlock (BlockType block)

void	ReadFlashOrExit (size_t offset, RawData data)

void	WriteFlashOrExit (size_t offset, ConstRawData data)

void	EraseFlashOrExit (size_t offset, size_t size)

bool	IsBlockInited (BlockType block)
	判断块是否已初始化 (Check if block is initialized).

bool	IsBlockEmpty (BlockType block)
	判断块是否为空 (Check if block is empty).

bool	IsBlockError (BlockType block)
	判断块是否损坏 (Check if block has an error).

bool	HasLastKey (size_t offset)

size_t	GetKeySize (size_t offset)

size_t	GetNextKey (size_t offset)

size_t	GetLastKey (BlockType block)

void	SetNestKeyExist (size_t offset, bool exist)

bool	KeyDataCompare (size_t offset, const void *data, size_t size)

bool	KeyNameCompare (size_t offset, const char *name)

size_t	SearchKey (const char *name)

Private Attributes
Flash &	flash_
	目标 Flash 存储设备 (Target Flash storage device).

uint8_t *	buffer_
	数据缓冲区 (Data buffer).

uint32_t	block_size_
	Flash 块大小 (Flash block size).

uint32_t	max_buffer_size_
	最大缓冲区大小 (Maximum buffer size).

Static Private Attributes
static constexpr uint32_t	FLASH_HEADER
	Flash 头部标识 (Flash header identifier).

static constexpr uint8_t	CHECKSUM_BYTE = 0x56
	校验字节 (Checksum byte).

Detailed Description

适用于不支持逆序写入的 Flash 存储的数据库实现 (Database implementation for Flash storage that does not support reverse writing).

This class manages key-value storage in a Flash memory region where data can only be written sequentially. It maintains a backup system to prevent data corruption. 此类管理 Flash 内存区域中的键值存储，其中数据只能顺序写入。它维护一个备份系统，以防止数据损坏。

Note: 若底层 Flash 读写擦失败，当前实现视为不可恢复故障并直接触发 REQUIRE。 If the underlying Flash read, write, or erase operation fails, the current implementation treats it as an unrecoverable fault and triggers REQUIRE immediately.

Definition at line 28 of file raw_sequential.hpp.

Member Enumeration Documentation

◆ BlockType

enum class LibXR::DatabaseRawSequential::BlockType : uint8_t

strongprivate

存储块类型 (Storage block type).

Enumerator
MAIN	主块 (Main block).
BACKUP	备份块 (Backup block).

Definition at line 107 of file raw_sequential.hpp.

  {
    MAIN = 0,   
    BACKUP = 1  
  };

Constructor & Destructor Documentation

◆ DatabaseRawSequential()

DatabaseRawSequential::DatabaseRawSequential	(	Flash &	flash,
		size_t	max_buffer_size = 256 )

explicit

构造函数，初始化 Flash 存储和缓冲区 (Constructor initializing Flash storage and buffer).

Parameters

flash	目标 Flash 存储设备 (Target Flash storage device).
max_buffer_size	最大缓冲区大小，默认 256 字节 (Maximum buffer size, default is 256 bytes).

Note: 包含动态内存分配。 Contains dynamic memory allocation.; max_buffer_size 必须不超过整片 Flash 容量的一半。 max_buffer_size must not exceed half of the total flash capacity.

Definition at line 11 of file raw_sequential.cpp.

    : flash_(flash), max_buffer_size_(max_buffer_size)
{
  ASSERT(flash.MinEraseSize() * 2 <= flash.Size());
  ASSERT(max_buffer_size <= flash.Size() / 2);
  auto block_num = static_cast<size_t>(flash.Size() / flash.MinEraseSize());
  block_size_ = block_num / 2 * flash.MinEraseSize();
  buffer_ = new uint8_t[max_buffer_size];
 
  Init();
}

Member Function Documentation

◆ Add()

ErrorCode LibXR::DatabaseRawSequential::Add ( KeyBase & key )

inlineoverridevirtual

添加新键到数据库 (Add a new key to the database).

Parameters

key	需要添加的键 (Key to add).

Returns: 操作结果 (Operation result).

Implements LibXR::Database.

Definition at line 98 of file raw_sequential.hpp.

  {
    return AddKey(key.name_, key.raw_data_.addr_, key.raw_data_.size_);
  }

◆ AddKey()

ErrorCode DatabaseRawSequential::AddKey	(	const char *	name,
		const void *	data,
		size_t	size )

private

Definition at line 293 of file raw_sequential.cpp.

{
  if (auto ans = SearchKey(name))
  {
    return SetKey(ans, data, size);
  }
 
  const uint32_t NAME_LEN = strlen(name) + 1;
  size_t last_key_offset = GetLastKey(BlockType::MAIN);
  size_t key_buf_offset =
      last_key_offset ? GetNextKey(last_key_offset) : LibXR::OffsetOf(&FlashInfo::key);
 
  size_t end_pos_offset = key_buf_offset + sizeof(KeyInfo) + NAME_LEN + size;
  if (end_pos_offset > max_buffer_size_ - 1)
  {
    return ErrorCode::FULL;
  }
 
  size_t data_ptr_offset = key_buf_offset + sizeof(KeyInfo);
  LibXR::Memory::FastCopy(buffer_ + data_ptr_offset, name, NAME_LEN);
  LibXR::Memory::FastCopy(buffer_ + data_ptr_offset + NAME_LEN, data, size);
 
  KeyInfo key_buf = {0, static_cast<uint8_t>(NAME_LEN), static_cast<uint32_t>(size)};
  LibXR::Memory::FastCopy(buffer_ + key_buf_offset, &key_buf, sizeof(KeyInfo));
  if (last_key_offset)
  {
    SetNestKeyExist(last_key_offset, 1);
  }
 
  Save();
  return ErrorCode::OK;
}

◆ EraseFlashOrExit()

void DatabaseRawSequential::EraseFlashOrExit	(	size_t	offset,
		size_t	size )

private

Definition at line 74 of file raw_sequential.cpp.

{
  REQUIRE(flash_.Erase(offset, size) == ErrorCode::OK);
}

◆ Get()

ErrorCode DatabaseRawSequential::Get ( Database::KeyBase & key )

overridevirtual

获取数据库中的键值 (Retrieve the key's value from the database).

Parameters

key	需要获取的键 (Key to retrieve).

Returns: 操作结果，如果找到则返回 ErrorCode::OK，否则返回 ErrorCode::NOT_FOUND (Operation result, returns ErrorCode::OK if found, otherwise ErrorCode::NOT_FOUND).

Implements LibXR::Database.

Definition at line 133 of file raw_sequential.cpp.

{
  auto ans = SearchKey(key.name_);
  if (!ans)
  {
    return ErrorCode::NOT_FOUND;
  }
 
  KeyInfo key_buffer;
  ReadFlashOrExit(ans, key_buffer);
 
  if (key.raw_data_.size_ != key_buffer.GetDataSize())
  {
    return ErrorCode::FAILED;
  }
 
  GetKeyData(ans, key.raw_data_);
 
  return ErrorCode::OK;
}

◆ GetKeyData()

ErrorCode DatabaseRawSequential::GetKeyData	(	size_t	offset,
		RawData	data )

private

Definition at line 356 of file raw_sequential.cpp.

{
  KeyInfo key;
  ReadFlashOrExit(offset, key);
  if (key.GetDataSize() > data.size_)
  {
    return ErrorCode::FAILED;
  }
  auto data_offset = offset + sizeof(KeyInfo) + key.GetNameLength();
  ReadFlashOrExit(data_offset, {data.addr_, key.GetDataSize()});
  return ErrorCode::OK;
}

◆ GetKeySize()

size_t DatabaseRawSequential::GetKeySize ( size_t offset )

private

Definition at line 225 of file raw_sequential.cpp.

{
  KeyInfo key;
  ReadFlashOrExit(offset, key);
  return sizeof(KeyInfo) + key.GetNameLength() + key.GetDataSize();
}

◆ GetLastKey()

size_t DatabaseRawSequential::GetLastKey ( BlockType block )

private

Definition at line 237 of file raw_sequential.cpp.

{
  if (IsBlockEmpty(block))
  {
    return 0;
  }
 
  size_t offset = LibXR::OffsetOf(&FlashInfo::key);
  while (HasLastKey(offset))
  {
    offset = GetNextKey(offset);
  }
  return offset;
}

◆ GetNextKey()

size_t DatabaseRawSequential::GetNextKey ( size_t offset )

private

Definition at line 232 of file raw_sequential.cpp.

{
  return offset + GetKeySize(offset);
}

◆ HasLastKey()

bool DatabaseRawSequential::HasLastKey ( size_t offset )

private

Definition at line 218 of file raw_sequential.cpp.

{
  KeyInfo key;
  ReadFlashOrExit(offset, key);
  return key.GetNextKeyExist();
}

◆ Init()

void DatabaseRawSequential::Init ( )

初始化数据库存储区，确保主备块正确 (Initialize database storage, ensuring main and backup blocks are valid).

Definition at line 79 of file raw_sequential.cpp.

{
  Memory::FastSet(buffer_, 0xFF, max_buffer_size_);
  FlashInfo* flash_data_ = reinterpret_cast<FlashInfo*>(buffer_);
  flash_data_->header = FLASH_HEADER;
  flash_data_->key = {0, 0, 0};
  buffer_[max_buffer_size_ - 1] = CHECKSUM_BYTE;
 
  if (!IsBlockInited(BlockType::BACKUP) || IsBlockError(BlockType::BACKUP))
  {
    InitBlock(BlockType::BACKUP);
  }
 
  if (IsBlockError(BlockType::MAIN))
  {
    if (IsBlockEmpty(BlockType::BACKUP))
    {
      InitBlock(BlockType::MAIN);
    }
    else
    {
      ReadFlashOrExit(block_size_, {buffer_, max_buffer_size_});
      EraseFlashOrExit(0, block_size_);
      WriteFlashOrExit(0, {buffer_, max_buffer_size_});
    }
  }
 
  Load();
}

◆ InitBlock()

void DatabaseRawSequential::InitBlock ( BlockType block )

private

Definition at line 154 of file raw_sequential.cpp.

{
  size_t offset = 0;
  if (block == BlockType::BACKUP)
  {
    offset = block_size_;
  }
 
  EraseFlashOrExit(offset, block_size_);
  WriteFlashOrExit(offset, {buffer_, max_buffer_size_});
}

◆ IsBlockEmpty()

bool DatabaseRawSequential::IsBlockEmpty ( BlockType block )

private

判断块是否为空 (Check if block is empty).

Parameters

block 需要检查的块 (Block to check).

Returns: 如果为空返回 true，否则返回 false (Returns true if empty, false otherwise).

Definition at line 189 of file raw_sequential.cpp.

{
  size_t offset = 0;
  if (block == BlockType::BACKUP)
  {
    offset = block_size_;
  }
  FlashInfo flash_data_;
  ReadFlashOrExit(offset, flash_data_);
  return flash_data_.key.GetNameLength() == 0;
}

◆ IsBlockError()

bool DatabaseRawSequential::IsBlockError ( BlockType block )

private

判断块是否损坏 (Check if block has an error).

Parameters

block 需要检查的块 (Block to check).

Returns: 如果损坏返回 true，否则返回 false (Returns true if corrupted, false otherwise).

Definition at line 206 of file raw_sequential.cpp.

{
  size_t offset = 0;
  if (block == BlockType::BACKUP)
  {
    offset = block_size_;
  }
  uint8_t checksum_byte = 0;
  ReadFlashOrExit(offset + max_buffer_size_ / sizeof(CHECKSUM_BYTE) - 1, checksum_byte);
  return checksum_byte != CHECKSUM_BYTE;
}

◆ IsBlockInited()

bool DatabaseRawSequential::IsBlockInited ( BlockType block )

private

判断块是否已初始化 (Check if block is initialized).

Parameters

block 需要检查的块 (Block to check).

Returns: 如果已初始化返回 true，否则返回 false (Returns true if initialized, false otherwise).

Definition at line 172 of file raw_sequential.cpp.

{
  size_t offset = 0;
  if (block == BlockType::BACKUP)
  {
    offset = block_size_;
  }
  FlashInfo flash_data_;
  ReadFlashOrExit(offset, flash_data_);
  return flash_data_.header == FLASH_HEADER;
}

◆ KeyDataCompare()

bool DatabaseRawSequential::KeyDataCompare	(	size_t	offset,
		const void *	data,
		size_t	size )

private

Definition at line 260 of file raw_sequential.cpp.

{
  KeyInfo key;
  ReadFlashOrExit(offset, key);
  size_t key_data_offset = offset + sizeof(KeyInfo) + key.GetNameLength();
  uint8_t data_buffer;
  for (size_t i = 0; i < size; i++)
  {
    ReadFlashOrExit(key_data_offset + i, data_buffer);
    if (data_buffer != ((uint8_t*)data)[i])
    {
      return true;
    }
  }
  return false;
}

◆ KeyNameCompare()

bool DatabaseRawSequential::KeyNameCompare	(	size_t	offset,
		const char *	name )

private

Definition at line 277 of file raw_sequential.cpp.

{
  KeyInfo key;
  ReadFlashOrExit(offset, key);
  for (size_t i = 0; i < key.GetNameLength(); i++)
  {
    uint8_t data_buffer;
    ReadFlashOrExit(offset + sizeof(KeyInfo) + i, data_buffer);
    if (data_buffer != name[i])
    {
      return true;
    }
  }
  return false;
}

◆ Load()

void DatabaseRawSequential::Load ( )

从 Flash 加载数据到缓冲区 (Load data from Flash into the buffer).

Definition at line 118 of file raw_sequential.cpp.

118{ ReadFlashOrExit(0, {buffer_, max_buffer_size_}); }

◆ ReadFlashOrExit()

void DatabaseRawSequential::ReadFlashOrExit	(	size_t	offset,
		RawData	data )

private

Definition at line 64 of file raw_sequential.cpp.

{
  REQUIRE(flash_.Read(offset, data) == ErrorCode::OK);
}

◆ Restore()

void DatabaseRawSequential::Restore ( )

还原存储数据，清空 Flash 区域 (Restore storage data, clearing Flash memory area).

Definition at line 120 of file raw_sequential.cpp.

{
  Memory::FastSet(buffer_, 0xFF, max_buffer_size_);
  FlashInfo* flash_data_ = reinterpret_cast<FlashInfo*>(buffer_);
  flash_data_->header = FLASH_HEADER;
  flash_data_->key = {0, 0, 0};
  buffer_[max_buffer_size_ - 1] = CHECKSUM_BYTE;
  EraseFlashOrExit(0, block_size_);
  EraseFlashOrExit(block_size_, block_size_);
  WriteFlashOrExit(0, {buffer_, max_buffer_size_});
  WriteFlashOrExit(block_size_, {buffer_, max_buffer_size_});
}

◆ Save()

void DatabaseRawSequential::Save ( )

保存当前缓冲区内容到 Flash (Save the current buffer content to Flash).

Definition at line 109 of file raw_sequential.cpp.

{
  EraseFlashOrExit(block_size_, block_size_);
  WriteFlashOrExit(block_size_, {buffer_, max_buffer_size_});
 
  EraseFlashOrExit(0, block_size_);
  WriteFlashOrExit(0, {buffer_, max_buffer_size_});
}

◆ SearchKey()

size_t DatabaseRawSequential::SearchKey ( const char * name )

private

Definition at line 369 of file raw_sequential.cpp.

{
  if (IsBlockEmpty(BlockType::MAIN))
  {
    return 0;
  }
 
  size_t key_offset = LibXR::OffsetOf(&FlashInfo::key);
  while (true)
  {
    if (KeyNameCompare(key_offset, name) == 0)
    {
      return key_offset;
    }
    if (!HasLastKey(key_offset))
    {
      break;
    }
    key_offset = GetNextKey(key_offset);
  }
  return 0;
}

◆ Set()

ErrorCode LibXR::DatabaseRawSequential::Set	(	KeyBase &	key,
		RawData	data )

inlineoverridevirtual

设置数据库中的键值 (Set the key's value in the database).

Parameters

key	目标键 (Target key).
data	需要存储的新值 (New value to store).

Returns: 操作结果 (Operation result).

Implements LibXR::Database.

Definition at line 87 of file raw_sequential.hpp.

  {
    return SetKey(key.name_, data.addr_, data.size_);
  }

◆ SetKey() [1/2]

ErrorCode DatabaseRawSequential::SetKey	(	const char *	name,
		const void *	data,
		size_t	size )

private

Definition at line 326 of file raw_sequential.cpp.

{
  if (size_t key_offset = SearchKey(name))
  {
    return SetKey(key_offset, data, size);
  }
  return ErrorCode::FAILED;
}

◆ SetKey() [2/2]

ErrorCode DatabaseRawSequential::SetKey	(	size_t	offset,
		const void *	data,
		size_t	size )

private

Definition at line 335 of file raw_sequential.cpp.

{
  ASSERT(offset != 0);
 
  KeyInfo key;
  ReadFlashOrExit(offset, key);
 
  if (key.GetDataSize() == size)
  {
    if (KeyDataCompare(offset, data, size))
    {
      LibXR::Memory::FastCopy(buffer_ + offset + sizeof(KeyInfo) + key.GetNameLength(),
                              data, size);
      Save();
    }
    return ErrorCode::OK;
  }
 
  return ErrorCode::FAILED;
}

◆ SetNestKeyExist()

void DatabaseRawSequential::SetNestKeyExist	(	size_t	offset,
		bool	exist )

private

Definition at line 252 of file raw_sequential.cpp.

{
  KeyInfo key;
  ReadFlashOrExit(offset, key);
  key.SetNextKeyExist(exist);
  LibXR::Memory::FastCopy(buffer_ + offset, &key, sizeof(KeyInfo));
}

◆ WriteFlashOrExit()

void DatabaseRawSequential::WriteFlashOrExit	(	size_t	offset,
		ConstRawData	data )

private

Definition at line 69 of file raw_sequential.cpp.

{
  REQUIRE(flash_.Write(offset, data) == ErrorCode::OK);
}

Field Documentation

◆ block_size_

uint32_t LibXR::DatabaseRawSequential::block_size_

private

Flash 块大小 (Flash block size).

Definition at line 215 of file raw_sequential.hpp.

◆ buffer_

uint8_t* LibXR::DatabaseRawSequential::buffer_

private

数据缓冲区 (Data buffer).

Definition at line 214 of file raw_sequential.hpp.

◆ CHECKSUM_BYTE

uint8_t LibXR::DatabaseRawSequential::CHECKSUM_BYTE = 0x56

staticconstexprprivate

校验字节 (Checksum byte).

Definition at line 211 of file raw_sequential.hpp.

◆ flash_

Flash& LibXR::DatabaseRawSequential::flash_

private

目标 Flash 存储设备 (Target Flash storage device).

Definition at line 213 of file raw_sequential.hpp.

◆ FLASH_HEADER

uint32_t LibXR::DatabaseRawSequential::FLASH_HEADER

staticconstexprprivate

Initial value:

=

0x12345678 + LIBXR_DATABASE_VERSION

LibXR::LIBXR_DATABASE_VERSION

static constexpr uint16_t LIBXR_DATABASE_VERSION

数据库存储格式版本号 (Database storage-format version).

Definition interface.hpp:17

Flash 头部标识 (Flash header identifier).

Definition at line 209 of file raw_sequential.hpp.

◆ max_buffer_size_

uint32_t LibXR::DatabaseRawSequential::max_buffer_size_

private

最大缓冲区大小 (Maximum buffer size).

Definition at line 216 of file raw_sequential.hpp.

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

src/middleware/database/raw_sequential.hpp
src/middleware/database/raw_sequential.cpp

Data Structures

Public Member Functions

Private Types

Private Member Functions

Private Attributes

Static Private Attributes

Detailed Description

Member Enumeration Documentation

◆ BlockType

Constructor & Destructor Documentation

◆ DatabaseRawSequential()

Member Function Documentation

◆ Add()

◆ AddKey()

◆ EraseFlashOrExit()

◆ Get()

◆ GetKeyData()

◆ GetKeySize()

◆ GetLastKey()

◆ GetNextKey()

◆ HasLastKey()

◆ Init()

◆ InitBlock()

◆ IsBlockEmpty()

◆ IsBlockError()

◆ IsBlockInited()

◆ KeyDataCompare()

◆ KeyNameCompare()

◆ Load()

◆ ReadFlashOrExit()

◆ Restore()

◆ Save()

◆ SearchKey()

◆ Set()

◆ SetKey() [1/2]

◆ SetKey() [2/2]

◆ SetNestKeyExist()

◆ WriteFlashOrExit()

Field Documentation

◆ block_size_

◆ buffer_

◆ CHECKSUM_BYTE

◆ flash_

◆ FLASH_HEADER

◆ max_buffer_size_