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

#include <database.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 }

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)

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 内存区域中的键值存储，其中数据只能顺序写入。它维护一个备份系统，以防止数据损坏。

Definition at line 158 of file database.hpp.

Member Enumeration Documentation

◆ BlockType

enum class LibXR::DatabaseRawSequential::BlockType : uint8_t

strongprivate

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

Definition at line 229 of file database.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).

Definition at line 10 of file database.cpp.

    : flash_(flash), max_buffer_size_(max_buffer_size)
{
  ASSERT(flash.MinEraseSize() * 2 <= flash.Size());
  if (max_buffer_size * 2 > flash.Size())
  {
    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 223 of file database.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 237 of file database.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) : OFFSET_OF(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;
}

◆ 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 77 of file database.cpp.

{
  auto ans = SearchKey(key.name_);
  if (!ans)
  {
    return ErrorCode::NOT_FOUND;
  }
 
  KeyInfo key_buffer;
  flash_.Read(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 300 of file database.cpp.

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

◆ GetKeySize()

size_t DatabaseRawSequential::GetKeySize ( size_t offset )

private

Definition at line 169 of file database.cpp.

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

◆ GetLastKey()

size_t DatabaseRawSequential::GetLastKey ( BlockType block )

private

Definition at line 181 of file database.cpp.

{
  if (IsBlockEmpty(block))
  {
    return 0;
  }
 
  size_t offset = OFFSET_OF(FlashInfo, key);
  while (HasLastKey(offset))
  {
    offset = GetNextKey(offset);
  }
  return offset;
}

◆ GetNextKey()

size_t DatabaseRawSequential::GetNextKey ( size_t offset )

private

Definition at line 176 of file database.cpp.

{
  return offset + GetKeySize(offset);
}

◆ HasLastKey()

bool DatabaseRawSequential::HasLastKey ( size_t offset )

private

Definition at line 162 of file database.cpp.

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

◆ Init()

void DatabaseRawSequential::Init ( )

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

Definition at line 25 of file database.cpp.

{
  memset(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
    {
      flash_.Read(block_size_, {buffer_, max_buffer_size_});
      flash_.Erase(0, block_size_);
      flash_.Write(0, {buffer_, max_buffer_size_});
    }
  }
 
  Load();
}

◆ InitBlock()

void DatabaseRawSequential::InitBlock ( BlockType block )

private

Definition at line 98 of file database.cpp.

{
  size_t offset = 0;
  if (block == BlockType::BACKUP)
  {
    offset = block_size_;
  }
 
  flash_.Erase(offset, block_size_);
  flash_.Write(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 133 of file database.cpp.

{
  size_t offset = 0;
  if (block == BlockType::BACKUP)
  {
    offset = block_size_;
  }
  FlashInfo flash_data_;
  flash_.Read(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 150 of file database.cpp.

{
  size_t offset = 0;
  if (block == BlockType::BACKUP)
  {
    offset = block_size_;
  }
  uint8_t checksum_byte = 0;
  flash_.Read(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 116 of file database.cpp.

{
  size_t offset = 0;
  if (block == BlockType::BACKUP)
  {
    offset = block_size_;
  }
  FlashInfo flash_data_;
  flash_.Read(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 204 of file database.cpp.

{
  KeyInfo key;
  flash_.Read(offset, key);
  size_t key_data_offset = offset + sizeof(KeyInfo) + key.GetNameLength();
  uint8_t data_buffer;
  for (size_t i = 0; i < size; i++)
  {
    flash_.Read(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 221 of file database.cpp.

{
  KeyInfo key;
  flash_.Read(offset, key);
  for (size_t i = 0; i < key.GetNameLength(); i++)
  {
    uint8_t data_buffer;
    flash_.Read(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 64 of file database.cpp.

64{ flash_.Read(0, {buffer_, max_buffer_size_}); }

◆ Restore()

void DatabaseRawSequential::Restore ( )

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

Definition at line 66 of file database.cpp.

{
  memset(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;
  flash_.Write(0, {buffer_, max_buffer_size_});
  flash_.Write(block_size_, {buffer_, max_buffer_size_});
}

◆ Save()

void DatabaseRawSequential::Save ( )

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

Definition at line 55 of file database.cpp.

{
  flash_.Erase(block_size_, block_size_);
  flash_.Write(block_size_, {buffer_, max_buffer_size_});
 
  flash_.Erase(0, block_size_);
  flash_.Write(0, {buffer_, max_buffer_size_});
}

◆ SearchKey()

size_t DatabaseRawSequential::SearchKey ( const char * name )

private

Definition at line 313 of file database.cpp.

{
  if (IsBlockEmpty(BlockType::MAIN))
  {
    return 0;
  }
 
  size_t key_offset = OFFSET_OF(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 212 of file database.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 270 of file database.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 279 of file database.cpp.

{
  ASSERT(offset != 0);
 
  KeyInfo key;
  flash_.Read(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 196 of file database.cpp.

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

Field Documentation

◆ block_size_

uint32_t LibXR::DatabaseRawSequential::block_size_

private

Flash 块大小 (Flash block size).

Definition at line 308 of file database.hpp.

◆ buffer_

uint8_t* LibXR::DatabaseRawSequential::buffer_

private

数据缓冲区 (Data buffer).

Definition at line 307 of file database.hpp.

◆ CHECKSUM_BYTE

uint8_t LibXR::DatabaseRawSequential::CHECKSUM_BYTE = 0x56

staticconstexprprivate

校验字节 (Checksum byte).

Definition at line 304 of file database.hpp.

◆ flash_

Flash& LibXR::DatabaseRawSequential::flash_

private

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

Definition at line 306 of file database.hpp.

◆ FLASH_HEADER

uint32_t LibXR::DatabaseRawSequential::FLASH_HEADER

staticconstexprprivate

Initial value:

=

0x12345678 + LIBXR_DATABASE_VERSION

Flash 头部标识 (Flash header identifier).

Definition at line 302 of file database.hpp.

◆ max_buffer_size_

uint32_t LibXR::DatabaseRawSequential::max_buffer_size_

private

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

Definition at line 309 of file database.hpp.

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

src/middleware/database.hpp
src/middleware/database.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()

◆ Get()

◆ GetKeyData()

◆ GetKeySize()

◆ GetLastKey()

◆ GetNextKey()

◆ HasLastKey()

◆ Init()

◆ InitBlock()

◆ IsBlockEmpty()

◆ IsBlockError()

◆ IsBlockInited()

◆ KeyDataCompare()

◆ KeyNameCompare()

◆ Load()

◆ Restore()

◆ Save()

◆ SearchKey()

◆ Set()

◆ SetKey() [1/2]

◆ SetKey() [2/2]

◆ SetNestKeyExist()

Field Documentation

◆ block_size_

◆ buffer_

◆ CHECKSUM_BYTE

◆ flash_

◆ FLASH_HEADER

◆ max_buffer_size_