LibXR::DatabaseRawSequential Class Reference

适用于不支持逆序写入的 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).

Private Member Functions
ErrorCode	AddKey (const char *name, const void *data, size_t size)
	添加键值对到数据库 (Add key-value pair to database).
ErrorCode	SetKey (const char *name, const void *data, size_t size)
	设置键值 (Set key value).
ErrorCode	SetKey (KeyInfo *key, const void *data, size_t size)
	设置指定键的值 (Set the value of a specified key).
uint8_t *	GetKeyData (KeyInfo *key)
	获取指定键的数据信息 (Retrieve the data associated with a key).
const char *	GetKeyName (KeyInfo *key)
	获取键的名称 (Retrieve the name of a key).
void	InitBlock (FlashInfo *block)
	初始化块数据 (Initialize block data).
bool	IsBlockInited (FlashInfo *block)
	判断块是否已初始化 (Check if block is initialized).
bool	IsBlockEmpty (FlashInfo *block)
	判断块是否为空 (Check if block is empty).
bool	IsBlockError (FlashInfo *block)
	判断块是否损坏 (Check if block has an error).
size_t	GetKeySize (KeyInfo *key)
	计算键的总大小 (Calculate total size of a key).
KeyInfo *	GetNextKey (KeyInfo *key)
	获取下一个键 (Get next key).
KeyInfo *	GetLastKey (FlashInfo *block)
	获取块中的最后一个键 (Get last key in block).
KeyInfo *	SearchKey (const char *name)
	查找键 (Search for key).
ErrorCode	Add (KeyBase &key) override
	添加新键到数据库 (Add a new key to the database).

Private Attributes
Flash &	flash_
	目标 Flash 存储设备 (Target Flash storage device).
uint8_t *	data_buffer_
	数据缓冲区 (Data buffer).
FlashInfo *	flash_data_
	Flash 数据存储区 (Pointer to the Flash data storage).
FlashInfo *	info_main_
	主存储区信息 (Main storage block information).
FlashInfo *	info_backup_
	备份存储区信息 (Backup storage block information).
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.

Constructor & Destructor Documentation

DatabaseRawSequential()

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

explicit

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

构造函数，初始化数据库存储，并设置缓冲区 (Constructor to initialize database storage and set buffer).

Parameters

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

Definition at line 16 of file database.cpp.

    : flash_(flash), max_buffer_size_(max_buffer_size)
{
  ASSERT(flash.min_erase_size_ * 2 <= flash.flash_area_.size_);
  if (max_buffer_size * 2 > flash.flash_area_.size_)
  {
    max_buffer_size = flash.flash_area_.size_ / 2;
  }
  auto block_num = static_cast<size_t>(flash.flash_area_.size_ / flash.min_erase_size_);
  block_size_ = block_num / 2 * flash.min_erase_size_;
  data_buffer_ = new uint8_t[max_buffer_size];
  flash_data_ = reinterpret_cast<FlashInfo*>(data_buffer_);
  info_main_ = reinterpret_cast<FlashInfo*>(flash.flash_area_.addr_);
  info_backup_ = reinterpret_cast<FlashInfo*>(
      reinterpret_cast<uint8_t*>(flash.flash_area_.addr_) + block_size_);
  Init();
}

Member Function Documentation

Add()

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

inlineoverrideprivatevirtual

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

Parameters

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

Returns

操作结果 (Operation result).

Implements LibXR::Database.

Definition at line 294 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

添加键值对到数据库 (Add key-value pair to database).

Parameters

name	键名 (Key name).
data	数据 (Data value).
size	数据大小 (Size of data).

Returns

操作结果 (Operation result).

Definition at line 186 of file database.cpp.

{
  if (auto ans = SearchKey(name))
  {
    return SetKey(ans, data, size);
  }
 
  const uint32_t NAME_LEN = strlen(name) + 1;
  KeyInfo* last_key = GetLastKey(flash_data_);
  KeyInfo* key_buf = last_key ? GetNextKey(last_key) : &flash_data_->key;
 
  const uint8_t* end_pos =
      reinterpret_cast<uint8_t*>(key_buf) + sizeof(KeyInfo) + NAME_LEN + size;
  if (end_pos > data_buffer_ + max_buffer_size_ - 1)
  {
    return ErrorCode::FULL;
  }
 
  uint8_t* data_ptr = reinterpret_cast<uint8_t*>(key_buf) + sizeof(KeyInfo);
  memcpy(data_ptr, name, NAME_LEN);
  memcpy(data_ptr + NAME_LEN, data, size);
 
  *key_buf = KeyInfo{0, static_cast<uint8_t>(NAME_LEN), static_cast<uint32_t>(size)};
  if (last_key)
  {
    last_key->SetNextKeyExist(1);
  }
 
  Save();
  return ErrorCode::OK;
}

Get()

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

inlineoverridevirtual

获取数据库中的键值 (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 308 of file database.hpp.

  {
    auto ans = SearchKey(key.name_);
    if (!ans)
    {
      return ErrorCode::NOT_FOUND;
    }
 
    if (key.raw_data_.size_ != ans->GetDataSize())
    {
      return ErrorCode::FAILED;
    }
 
    memcpy(key.raw_data_.addr_, GetKeyData(ans), ans->GetDataSize());
 
    return ErrorCode::OK;
  }

GetKeyData()

uint8_t * DatabaseRawSequential::GetKeyData ( KeyInfo * key )

private

获取指定键的数据信息 (Retrieve the data associated with a key).

获取键的数据信息 (Retrieve the data associated with a key).

Parameters

key	目标键 (Key to retrieve data from).

Returns

指向数据的指针 (Pointer to the key's data).

This function returns a pointer to the data section of the specified key. 此函数返回指向指定键的数据部分的指针。

Parameters

key	指向目标键的指针 (Pointer to the key whose data is retrieved).

Returns

返回数据的起始地址 (Returns a pointer to the start of the data).

Definition at line 274 of file database.cpp.

{
  return reinterpret_cast<uint8_t*>(key) + sizeof(KeyInfo) + key->GetNameLength();
}

GetKeyName()

const char * DatabaseRawSequential::GetKeyName ( KeyInfo * key )

private

获取键的名称 (Retrieve the name of a key).

Parameters

key	目标键 (Key to retrieve the name from).

Returns

指向键名的指针 (Pointer to the key name).

This function returns a pointer to the name section of the specified key. 此函数返回指向指定键名称部分的指针。

Parameters

key	指向目标键的指针 (Pointer to the key whose name is retrieved).

Returns

返回键名的起始地址 (Returns a pointer to the start of the key name).

Definition at line 288 of file database.cpp.

{
  return reinterpret_cast<const char*>(key) + sizeof(KeyInfo);
}

GetKeySize()

size_t DatabaseRawSequential::GetKeySize ( KeyInfo * key )

private

计算键的总大小 (Calculate total size of a key).

Parameters

key	键信息 (Key information).

Returns

键的大小 (Size of the key).

Definition at line 143 of file database.cpp.

{
  return sizeof(KeyInfo) + key->GetNameLength() + key->GetDataSize();
}

GetLastKey()

DatabaseRawSequential::KeyInfo * DatabaseRawSequential::GetLastKey ( FlashInfo * block )

private

获取块中的最后一个键 (Get last key in block).

Parameters

block

目标块 (Block to check).

Returns

最后一个键的指针，如果块为空返回 nullptr (Pointer to last key, or nullptr if block is empty).

Definition at line 164 of file database.cpp.

{
  if (IsBlockEmpty(block))
  {
    return nullptr;
  }
 
  KeyInfo* key = &block->key;
  while (key->GetNextKeyExist())
  {
    key = GetNextKey(key);
  }
  return key;
}

GetNextKey()

DatabaseRawSequential::KeyInfo * DatabaseRawSequential::GetNextKey ( KeyInfo * key )

private

获取下一个键 (Get next key).

Parameters

key	当前键 (Current key).

Returns

下一个键 (Next key).

Definition at line 153 of file database.cpp.

{
  return reinterpret_cast<KeyInfo*>(reinterpret_cast<uint8_t*>(key) + GetKeySize(key));
}

Init()

void DatabaseRawSequential::Init

(

)

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

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

Definition at line 38 of file database.cpp.

{
  memset(data_buffer_, 0xFF, max_buffer_size_);
  flash_data_->header = FLASH_HEADER;
  flash_data_->key = {0, 0, 0};
  data_buffer_[max_buffer_size_ - 1] = CHECKSUM_BYTE;
 
  if (!IsBlockInited(info_backup_) || IsBlockError(info_backup_))
  {
    InitBlock(info_backup_);
  }
 
  if (IsBlockError(info_main_))
  {
    if (IsBlockEmpty(info_backup_))
    {
      InitBlock(info_main_);
    }
    else
    {
      flash_.Erase(0, block_size_);
      flash_.Write(0, {reinterpret_cast<uint8_t*>(info_backup_), max_buffer_size_});
    }
  }
 
  memcpy(data_buffer_, info_main_, max_buffer_size_);
}

InitBlock()

void DatabaseRawSequential::InitBlock ( FlashInfo * block )

private

初始化块数据 (Initialize block data).

Parameters

block

需要初始化的块 (Block to initialize).

Definition at line 96 of file database.cpp.

{
  flash_.Erase(reinterpret_cast<size_t>(block) -
                   reinterpret_cast<size_t>(flash_.flash_area_.addr_),
               block_size_);
  flash_.Write(reinterpret_cast<size_t>(block) -
                   reinterpret_cast<size_t>(flash_.flash_area_.addr_),
               {data_buffer_, block_size_});
}

IsBlockEmpty()

bool DatabaseRawSequential::IsBlockEmpty ( FlashInfo * block )

private

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

Parameters

block

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

Returns

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

Definition at line 122 of file database.cpp.

{
  return block->key.GetNameLength() == 0;
}

IsBlockError()

bool DatabaseRawSequential::IsBlockError ( FlashInfo * 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 132 of file database.cpp.

{
  return reinterpret_cast<uint8_t*>(
             block)[max_buffer_size_ / sizeof(CHECKSUM_BYTE) - 1] != CHECKSUM_BYTE;
}

IsBlockInited()

bool DatabaseRawSequential::IsBlockInited ( FlashInfo * block )

private

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

Parameters

block

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

Returns

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

Definition at line 112 of file database.cpp.

{
  return block->header == FLASH_HEADER;
}

Load()

void DatabaseRawSequential::Load

(

)

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

加载数据到缓冲区 (Load data into buffer).

Definition at line 81 of file database.cpp.

{ memcpy(data_buffer_, info_main_, max_buffer_size_); }

Restore()

void DatabaseRawSequential::Restore

(

)

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

还原存储数据 (Restore storage data).

Definition at line 86 of file database.cpp.

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

Save()

void DatabaseRawSequential::Save

(

)

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

保存数据到存储器 (Save data to storage).

Definition at line 69 of file database.cpp.

{
  flash_.Erase(block_size_, block_size_);
  flash_.Write(block_size_, {reinterpret_cast<uint8_t*>(info_main_), max_buffer_size_});
 
  flash_.Erase(0, block_size_);
  flash_.Write(0, {data_buffer_, max_buffer_size_});
}

SearchKey()

DatabaseRawSequential::KeyInfo * DatabaseRawSequential::SearchKey ( const char * name )

private

查找键 (Search for key).

Parameters

name	需要查找的键名 (Key name to search).

Returns

指向找到的键的指针，若不存在则返回 nullptr (Pointer to found key, or nullptr if not found).

Definition at line 299 of file database.cpp.

{
  if (IsBlockEmpty(flash_data_))
  {
    return nullptr;
  }
 
  KeyInfo* key = &flash_data_->key;
  while (true)
  {
    if (strcmp(name, GetKeyName(key)) == 0)
    {
      return key;
    }
    if (!key->GetNextKeyExist())
    {
      break;
    }
    key = GetNextKey(key);
  }
  return nullptr;
}

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 333 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

设置键值 (Set key value).

Parameters

name	键名 (Key name).
data	数据 (Data value).
size	数据大小 (Size of data).

Returns

操作结果 (Operation result).

Definition at line 225 of file database.cpp.

{
  if (KeyInfo* key = SearchKey(name))
  {
    return SetKey(key, data, size);
  }
  return ErrorCode::FAILED;
}

SetKey() [2/2]

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

private

设置指定键的值 (Set the value of a specified key).

This function updates the key's data if the new size matches the existing size. If the data differs, it will be updated and saved. 此函数在新数据大小与现有数据大小匹配时更新键的值。如果数据不同，则会进行更新并保存。

Parameters

key	指向要更新的键的指针 (Pointer to the key to update).
data	指向要写入的数据 (Pointer to the data to be written).
size	数据大小 (Size of the data).

Returns

返回操作结果，成功返回 ErrorCode::OK，失败返回 ErrorCode::FAILED (Returns the operation result: ErrorCode::OK on success, ErrorCode::FAILED on failure).

Definition at line 248 of file database.cpp.

{
  ASSERT(key != nullptr);
 
  if (key->GetDataSize() == size)
  {
    if (memcmp(GetKeyData(key), data, size) != 0)
    {
      memcpy(GetKeyData(key), data, size);
      Save();
    }
    return ErrorCode::OK;
  }
 
  return ErrorCode::FAILED;
}

Field Documentation

block_size_

uint32_t LibXR::DatabaseRawSequential::block_size_

private

Flash 块大小 (Flash block size).

Definition at line 276 of file database.hpp.

CHECKSUM_BYTE

uint8_t LibXR::DatabaseRawSequential::CHECKSUM_BYTE = 0x56

staticconstexprprivate

校验字节 (Checksum byte).

Definition at line 269 of file database.hpp.

data_buffer_

uint8_t* LibXR::DatabaseRawSequential::data_buffer_

private

数据缓冲区 (Data buffer).

Definition at line 272 of file database.hpp.

flash_

Flash& LibXR::DatabaseRawSequential::flash_

private

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

Definition at line 271 of file database.hpp.

flash_data_

FlashInfo* LibXR::DatabaseRawSequential::flash_data_

private

Flash 数据存储区 (Pointer to the Flash data storage).

Definition at line 273 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 267 of file database.hpp.

info_backup_

FlashInfo* LibXR::DatabaseRawSequential::info_backup_

private

备份存储区信息 (Backup storage block information).

Definition at line 275 of file database.hpp.

info_main_

FlashInfo* LibXR::DatabaseRawSequential::info_main_

private

主存储区信息 (Main storage block information).

Definition at line 274 of file database.hpp.

max_buffer_size_

uint32_t LibXR::DatabaseRawSequential::max_buffer_size_

private

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

Definition at line 277 of file database.hpp.

---

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

• src/middleware/database.hpp
• src/middleware/database.cpp