版本：0.1 | 日期：2026-07-03 | 路径： platforms/components/xtiny/xt_mem/

一、概述

xt_mem 是 xtiny 内存分配抽象层，提供两套接口：标准 C 风格基本分配（ malloc / calloc / realloc / free ）和带能力标志的扩展分配（ caps_malloc / caps_realloc / caps_free ）。扩展接口通过 caps 位域描述内存需求（区域、对齐、属性），平台层按自身能力裁剪实现。

一句话设计理念 ：基本接口保证通用性， caps 接口为平台优化留出扩展点，未支持的能力静默忽略。

1.1 依赖

依赖	用途
xt_error.h	错误码定义（ XT_EOK / XT_EINVAL ）

二、核心概念

2.1 两套接口

接口层	函数	用途
基础 API	xt_mem_malloc / xt_mem_calloc / xt_mem_realloc / xt_mem_free	标准 C 内存分配，所有平台必须实现
Caps API	xt_mem_caps_malloc / xt_mem_caps_realloc / xt_mem_caps_free	带能力描述的内存分配，平台按需实现
便捷宏	xt_malloc / xt_calloc / xt_realloc / xt_free / xt_caps_malloc / xt_caps_realloc / xt_caps_free	基础 API 和 Caps API 的简短别名

基础 API 就是标准 malloc / calloc / realloc / free 的语义。Caps API 在此基础上增加一个 caps 参数，编码所需的内存属性。

2.2 Caps 位域

caps 是一个 uint32_t ，按位域编码三层信息：

bits[ 3: 0]  region  区域选择（4 bit）
bits[ 7: 4]  align   对齐粒度（4 bit）
bits[15: 8]  flags   属性标志（8 bit）

字段	偏移	宽度	说明
region	XT_MEM_CAP_REGION_S (0)	4	内存区域
align	XT_MEM_CAP_ALIGN_S (4)	4	对齐要求
flags	XT_MEM_CAP_FLAG_S (8)	8	特殊属性

2.3 区域（region）— 理论 vs 现实

区域是一个 目标无关的抽象 ，意图让调用者声明所需内存的物理位置。头文件定义了 8 种区域：

宏	值	含义
XT_MEM_CAP_DEFAULT	0	默认内部内存
XT_MEM_CAP_EXTERNAL	1	外部内存（如 PSRAM）
XT_MEM_CAP_REGION_0 ~ XT_MEM_CAP_REGION_5	2~7	平台自定义区域

但是，区域是否被尊重完全取决于平台实现。当前实现中 region 不被解析 ，所有分配统一走内部内存。如果业务依赖 EXTERNAL 来获取 PSRAM 内存，在 lm620 上实际得到的是普通内部内存——调用者需确认目标平台是否支持对应 region。

2.4 对齐机制

对齐值从 caps 的 align 字段解码：

align 字段值	对应宏	对齐字节
0	XT_MEM_CAP_ALIGN_8	8 位（1 字节，即不对齐）
1	XT_MEM_CAP_ALIGN_16	16 位（2 字节）
2	XT_MEM_CAP_ALIGN_32	32 位（4 字节）
3	XT_MEM_CAP_ALIGN_64	64 位（8 字节）

对齐 ≤ 8 字节时使用默认系统分配；对齐 > 8 字节时使用带对齐能力的分配。

2.5 标志位

宏	值	含义
XT_MEM_CAP_RESET	1 << 8	分配后将内存清零
XT_MEM_CAP_DMA	1 << 9	内存需 DMA 可达
XT_MEM_CAP_EXEC	1 << 10	内存需可执行

当前实现中 仅有 RESET 被处理 ：分配成功后 memset(ptr, 0, size) 。 DMA 和 EXEC 标志被忽略——调用者不能依赖它们生效。

2.6 caps_realloc 行为差异

标准 realloc 在可能时尝试原地扩展。但 xt_mem_caps_realloc 始终采用 alloc-copy-free 三段式 ：

用新 size+caps 分配新内存
memcpy 旧内容到新内存（拷贝字节数 = 新 size）
释放旧内存

这意味着：(1) 不存在原地扩展，(2) ptr 传入 NULL 等效于 xt_mem_caps_malloc，(3) size 传入 0 且 ptr 非空时释放旧内存返回 NULL。

2.7 caps_free 配对规则

分配函数	必须使用的释放函数
xt_mem_malloc / xt_mem_calloc / xt_mem_realloc	xt_mem_free
xt_mem_caps_malloc / xt_mem_caps_realloc	xt_mem_caps_free

xt_mem_caps_free 与通过带对齐分配的内存配对释放。 混用会导致未定义行为 。

三、API 参考

以下为函数签名大纲，完整的参数说明、返回值、注意事项请查看 xt_mem（内存管理）。

3.1 基础分配

函数签名	说明
void *xt_mem_malloc(size_t size)	分配内存
void *xt_mem_calloc(size_t count, size_t size)	分配并清零内存
void xt_mem_realloc(void ptr, size_t size)	重新分配内存
xt_err_t xt_mem_free(void *ptr)	释放内存

3.2 带能力的分配

函数签名	说明
void *xt_mem_caps_malloc(size_t size, uint32_t caps)	分配带能力标志的内存
void xt_mem_caps_realloc(void ptr, size_t size, uint32_t caps)	重新分配带能力标志的内存
xt_err_t xt_mem_caps_free(void *ptr)	释放通过 caps 分配的内存

3.3 便捷宏

宏	等价函数
xt_malloc(size)	xt_mem_malloc(size)
xt_calloc(count, size)	xt_mem_calloc((count), (size))
xt_realloc(ptr, size)	xt_mem_realloc((ptr), (size))
xt_free(ptr)	xt_mem_free(ptr)
xt_caps_malloc(size, caps)	xt_mem_caps_malloc((size), (caps))
xt_caps_realloc(ptr, size, caps)	xt_mem_caps_realloc((ptr), (size), (caps))
xt_caps_free(ptr)	xt_mem_caps_free(ptr)

四、常见模式

4.1 基本分配与释放

#include "xt_mem.h"
 
void *buf = xt_malloc(1024);
if (!buf) {
    return;
}
memset(buf, 0, 1024);
xt_free(buf);

4.2 带对齐的分配

// 分配 256 字节、64 位对齐的内存
void *buf = xt_caps_malloc(256, XT_MEM_CAP_ALIGN_64);
if (!buf) {
    return;
}
xt_caps_free(buf);

4.3 对齐 + 清零

// 32 位对齐 + 分配后清零
void *buf = xt_caps_malloc(128, XT_MEM_CAP_ALIGN_32 | XT_MEM_CAP_RESET);
// buf 已是对齐且清零的
xt_caps_free(buf);

4.4 caps_realloc 使用

// 初始分配
void *buf = xt_caps_malloc(64, XT_MEM_CAP_ALIGN_64);
// 扩容
void *new_buf = xt_caps_realloc(buf, 128, XT_MEM_CAP_ALIGN_64);
if (new_buf) {
    buf = new_buf;
}
xt_caps_free(buf);

五、已知行为与限制

项目	当前平台行为
region 字段	不支持，所有分配统一走默认内部内存
XT_MEM_CAP_EXTERNAL	被忽略，不会分配到 PSRAM
对齐 > 8 字节	走带对齐能力的分配
对齐 ≤ 8 字节	走系统默认分配
XT_MEM_CAP_RESET	支持，分配后 memset 清零
XT_MEM_CAP_DMA	不支持，忽略
XT_MEM_CAP_EXEC	不支持，忽略
caps_realloc	始终 alloc-copy-free，不存在原地扩展
caps_malloc(0, ...)	返回 NULL
caps_free(NULL)	返回 XT_EINVAL