2、Metadata数据结构设计：基础数据类型定义、结构体设计原则、内存对齐与字节序考虑

好，咱们进入第二章。这一章我打算聊聊Metadata的数据结构设计。说实话，这部分是HAL层里最容易被忽视、但坑最多的地方。你想想看，Metadata说白了就是一堆描述数据的数据，如果它的结构设计得不好，上层应用解析起来会非常痛苦。

我个人习惯，在设计任何Metadata结构之前，先想清楚三件事：数据从哪里来、要存到哪里去、谁会用这些数据。想清楚这三点，数据结构的大方向就不会跑偏。

2.1 基础数据类型定义

在嵌入式系统里，数据类型不能像PC上那么随意。我见过不少项目，直接在结构体里用int、long，结果换了个编译器就出问题。为什么？因为C标准只规定了int至少16位，但具体是多少，看编译器心情。

所以，我的做法是——显式定义固定宽度的数据类型。比如这样：

typedef uint8_t  metadata_u8;
typedef uint16_t metadata_u16;
typedef uint32_t metadata_u32;
typedef uint64_t metadata_u64;

typedef int8_t   metadata_s8;
typedef int16_t  metadata_s16;
typedef int32_t  metadata_s32;
typedef int64_t  metadata_s64;

typedef float    metadata_f32;   // 单精度，32位
typedef double   metadata_f64;   // 双精度，64位

嗯，这里要注意。有些芯片不支持浮点运算，或者浮点运算开销很大。我在一个低功耗蓝牙项目里就吃过这个亏——结构体里塞了个float，结果每次解析都要软浮点模拟，功耗直接飙上去。后来我改成用定点数表示，问题就解决了。

除了基本类型，我还会定义一些特殊标记类型：

typedef uint32_t metadata_tag_t;   // 标签ID，4字节对齐
typedef uint16_t metadata_len_t;   // 数据长度，2字节对齐
typedef uint8_t  metadata_flag_t;  // 标志位，1字节

为什么要单独定义？因为这样改起来方便。比如某天需求变了，tag要从32位改成64位，我只需要改这一处typedef，而不是满世界找uint32_t去替换。

static_assert(sizeof(metadata_u32) == 4, "metadata_u32 must be 4 bytes");

2.2 结构体设计原则

结构体设计，说白了就是怎么把数据组织得既紧凑又好用。我总结了三条原则，你可以参考一下：

原则一：按访问频率排序

经常被访问的字段放在前面。为什么？因为CPU访问结构体第一个成员时，不需要额外的偏移计算。我在一个摄像头ISP的HAL层里，把最常用的曝光时间、增益值放在结构体头部，性能提升了大概5%。

原则二：按对齐要求分组

把相同对齐要求的字段放在一起。比如所有4字节对齐的放一块，所有2字节对齐的放一块。这样编译器填充的padding最少，结构体更紧凑。

原则三：预留扩展位

这个我特别想强调。你永远不知道产品经理明天会加什么需求。所以，我习惯在每个结构体末尾预留一些reserved字段：

typedef struct {
    metadata_tag_t tag_id;          // 4字节
    metadata_len_t data_len;        // 2字节
    metadata_flag_t flags;          // 1字节
    uint8_t reserved1;              // 1字节，凑齐8字节对齐
    
    uint8_t data[64];               // 实际数据
    
    uint32_t reserved2[4];          // 预留16字节给未来扩展
} metadata_entry_t;

我曾经在一个项目里没留扩展位，结果后期要加个时间戳字段，整个结构体大小变了，所有依赖它的模块都得重新编译。那叫一个酸爽。

2.3 内存对齐

内存对齐这个话题，说简单也简单，说复杂也复杂。核心就一句话：结构体成员的地址，必须能被它自身大小整除。

比如一个uint32_t的变量，它的地址必须是4的倍数。如果不是，某些CPU会直接报错，有些虽然能读但性能会下降。我记得在ARM Cortex-M4上做过测试，未对齐访问比对齐访问慢了将近3倍。

来看一个典型的对齐问题：

typedef struct {
    uint8_t  a;    // 1字节，偏移0
    uint32_t b;    // 4字节，偏移1？不行，必须偏移4
    uint16_t c;    // 2字节，偏移8
} bad_example_t;
// 实际大小：12字节（1 + 3填充 + 4 + 2 + 2填充）

看到了吗？因为b要对齐到4字节，a后面被填充了3个字节。如果调整一下顺序：

typedef struct {
    uint32_t b;    // 4字节，偏移0
    uint16_t c;    // 2字节，偏移4
    uint8_t  a;    // 1字节，偏移6
} good_example_t;
// 实际大小：8字节（4 + 2 + 1 + 1填充）

同样的数据，大小从12字节变成了8字节。在嵌入式系统里，这4个字节可能就是压死骆驼的最后一根稻草。

2.4 字节序考虑

字节序，也就是大小端问题。在HAL层里，这是个绕不开的话题。为什么？因为你的嵌入式设备可能是小端（ARM、x86），但通信协议或者文件格式可能是大端（网络字节序、某些传感器）。

我的做法是：在Metadata结构体里，统一使用小端存储。为什么选小端？因为大部分嵌入式CPU都是小端，这样在本地处理时不需要转换。只有在网络传输或者写入文件时，才做一次大小端转换。

具体实现，我会提供一组转换宏：

// 小端转大端
#define METADATA_HTON16(x)  ((((x) & 0xFF) << 8) | (((x) >> 8) & 0xFF))
#define METADATA_HTON32(x)  ((((x) & 0xFF) << 24) | \
                             (((x) & 0xFF00) << 8) | \
                             (((x) & 0xFF0000) >> 8) | \
                             (((x) >> 24) & 0xFF))

// 大端转小端
#define METADATA_NTOH16(x)  METADATA_HTON16(x)
#define METADATA_NTOH32(x)  METADATA_HTON32(x)

你可能会问，为什么不用系统自带的htonl、ntohl？因为那些函数依赖操作系统，在裸机环境下不一定有。自己定义一套，移植性更好。

另外，我建议在结构体里加一个魔数（Magic Number）来标记字节序：

typedef struct {
    uint32_t magic;      // 固定为 0x12345678
    // ... 其他字段
} metadata_header_t;

解析时检查magic的值。如果是0x12345678，说明是小端；如果是0x78563412，说明是大端，需要做转换。这个技巧我在一个多平台项目中用过，效果非常好。

好了，这一章就到这里。下一章我会讲Metadata的存储与索引策略，包括怎么在有限的Flash空间里高效地查找和更新Metadata。到时候见。