Rust高效序列化存储库sequential-storage的使用，提供顺序数据存储与快速读写功能

Sequential-storage是一个用于在闪存中存储数据并最小化擦除周期的Rust库。它提供了两种数据结构：

1. Map：键值对存储
2. Queue：FIFO存储

每个数据结构都位于自己的模块中。请参阅模块文档以获取更多信息和示例。

注意： 确保不要在闪存中混合使用数据结构！例如，不能从推送队列的闪存区域中获取键值项。

状态

该库已在Tweede golf内部和外部的多个生产项目中使用。

闪存中的表示形式尚未稳定。这也遵循语义化版本控制：

• 对闪存表示形式的重大更改将导致主版本号增加
• 功能添加将导致次版本号增加
  • 这总是向后兼容的。例如，由1.0.0创建的数据可由1.1.0使用
  • 这可能不向前兼容。例如，由1.0.1创建的数据可能无法由1.0.0使用
• 1.0之后，补丁版本仅修复错误且不更改闪存表示形式

示例

以下是使用sequential-storage的完整示例代码：

use sequential_storage::map::{Map, NoCache};
use embedded_storage::nor_flash::{NorFlash, ReadNorFlash};

// 假设我们有一个实现NorFlash trait的闪存设备
struct MockFlash {
    data: Vec<u8>,
    page_size: usize,
}

impl NorFlash for MockFlash {
    const READ_SIZE: usize = 1;
    const WRITE_SIZE: usize = 1;
    const ERASE_SIZE: usize = 4096; // 假设页大小为4KB

    fn erase(&mut self, from: u32, to: u32) -> Result<(), Self::Error> {
        // 擦除闪存区域
        Ok(())
    }

    fn write(&mut self, offset: u32, bytes: &[u8]) -> Result<(), Self::Error> {
        // 写入数据到闪存
        Ok(())
    }
}

impl ReadNorFlash for MockFlash {
    const READ_SIZE: usize = 1;

    fn read(&mut self, offset: u32, bytes: &mut [u8]) -> Result<(), Self::Error> {
        // 从闪存读取数据
        Ok(())
    }

    fn capacity(&self) -> usize {
        self.data.len()
    }
}

fn main() {
    // 创建模拟闪存设备
    let mut flash = MockFlash {
        data: vec![0xFF; 4096 * 4], // 4页闪存
        page_size: 4096,
    };

    // 创建Map实例，不使用缓存
    let mut map = Map::<_, u32, String, NoCache>::new(&mut flash);
    
    // 存储键值对
    map.insert(&1, &"Value1".to_string()).unwrap();
    map.insert(&2, &"Value2".to_string()).unwrap();
    
    // 读取值
    let value = map.get(&1).unwrap();
    println!("Value for key 1: {}", value);
    
    // 删除键
    map.remove(&1).unwrap();
    
    // 检查键是否存在
    println!("Contains key 1: {}", map.contains_key(&1).unwrap());
}

完整示例代码

以下是一个更完整的示例，展示了如何使用sequential-storage的Map和Queue功能：

use sequential_storage::{map::{Map, PagePointerCache}, queue::Queue};
use embedded_storage::nor_flash::{NorFlash, ReadNorFlash};

// 实现NorFlash trait的闪存模拟
struct FlashDevice {
    data: Vec<u8>,
    erase_size: usize,
}

impl NorFlash for FlashDevice {
    const READ_SIZE: usize = 1;
    const WRITE_SIZE: usize = 1;
    const ERASE_SIZE: usize = 4096; // 4KB页大小

    fn erase(&mut self, from: u32, to: u32) -> Result<(), Self::Error> {
        let start = from as usize;
        let end = to as usize;
        self.data[start..end].fill(0xFF);
        Ok(())
    }

    fn write(&mut self, offset: u32, bytes: &[u8]) -> Result<(), Self::Error> {
        let start = offset as usize;
        self.data[start..start + bytes.len()].copy_from_slice(bytes);
        Ok(())
    }
}

impl ReadNorFlash for FlashDevice {
    const READ_SIZE: usize = 1;

    fn read(&mut self, offset: u32, bytes: &mut [u8]) -> Result<(), Self::Error> {
        let start = offset as usize;
        bytes.copy_from_slice(&self.data[start..start + bytes.len()]);
        Ok(())
    }

    fn capacity(&self) -> usize {
        self.data.len()
    }
}

fn main() {
    // 初始化闪存设备 (8页，每页4KB)
    let mut flash = FlashDevice {
        data: vec![0xFF; 4096 * 8],
        erase_size: 4096,
    };

    // 使用PagePointerCache的Map示例
    {
        let mut map = Map::<_, u32, String, PagePointerCache>::new(&mut flash);
        
        // 插入数据
        map.insert(&1, &"Config1".to_string()).unwrap();
        map.insert(&2, &"Config2".to_string()).unwrap();
        
        // 读取并打印数据
        if let Some(val) = map.get(&1).unwrap() {
            println!("Config1: {}", val);
        }
        
        // 更新数据
        map.insert(&1, &"UpdatedConfig1".to_string()).unwrap();
        
        // 遍历所有键
        for key in map.keys().unwrap() {
            println!("Key: {}", key);
        }
    }

    // Queue示例
    {
        let mut queue = Queue::new(&mut flash);
        
        // 推送数据
        queue.push(b"Message1").unwrap();
        queue.push(b"Message2").unwrap();
        
        // 弹出并打印数据
        while let Some(data) = queue.pop().unwrap() {
            println!("Popped: {:?}", data);
        }
    }
}

特性

• 键值数据存储(Map)
  • 用户定义的键和值类型
  • 非常适合创建配置
• FIFO队列数据存储(Queue)
  • 在内存中存储字节切片
  • 非常适合缓存数据
• 简单API：
  • 只需调用你认为需要的函数
  • 无需担心其他任何事情
• 项目头CRC保护
• 项目数据CRC保护
• 断电安全
  • 系统总是正常或完全可恢复
• 忽略损坏的项目
• 可选缓存以加速操作
• 磨损均衡
  • 页面循环使用，因此所有页面都会被擦除相同的次数
• 基于embedded-storage构建
  • 这是唯一必需的依赖项

缓存选项

有多种缓存选项可以加速操作：

内部工作原理

为了节省擦除周期，该库仅在页面上真正追加数据。具体如何完成取决于使用的是Map还是Queue。

页面和页面状态

闪存被划分为多个页面。页面可以处于三种状态：

1. 打开 - 页面处于擦除状态
2. 部分打开 - 页面已被写入，但尚未满
3. 关闭 - 页面已被完全写入

页面的状态被编码到页面的第一个和最后一个字中。如果两个字都是FF(擦除)，则页面是打开的。如果第一个字用标记写入，则页面是部分打开的。如果两个字都被写入，则页面是关闭的。

项目结构

所有数据都存储为一个项目。一个项目由包含数据长度的头、该长度的CRC、数据CRC和一些数据组成。当其数据CRC字段为0时，项目被视为已擦除。

长度是一个u16，因此任何项目不能长于0xFFFF或页面大小 - 项目头(填充到字边界) - 页面状态(2个字)。

Map工作流程

Map将每个键值存储为一个项目。每个新值都附加在最后一个部分打开的页面或最后一个关闭页面之后的第一个打开页面上。

一旦页面满了，它将被关闭，下一个页面将需要存储项目。然而，有时需要擦除一个旧页面。检查要擦除页面上所有项目。如果在页面上找到的项目没有比更新的值，它将从要擦除的页面复制到当前部分打开的页面。

Queue工作流程

当推送时，搜索放置项目的最年轻位置。如果它不适合，它将返回错误或擦除旧页面(如果指定它可以)。

窥视和弹出查看它能找到的最旧数据。当弹出时，项目也会被擦除。当使用peek_many时，可以查看从最旧到最新的所有数据。