跳至主要內容

堆内存管理

学习阁2026/7/16大约 33 分钟内核组件内核内存管理堆内存

堆内存管理

📚 本节导读

学习时长: 约 30 分钟
难度级别: ⭐⭐⭐☆☆
前置知识: 4.4 内存管理、C 语言动态内存（malloc/free）

堆内存（Heap）是 OneOS 中最灵活的内存分配方式。它允许在运行时按需分配任意大小的内存块，并在使用完毕后释放。OneOS 不仅提供了简洁的默认堆 API（与标准 C 库风格一致），还支持多堆实例的管理，方便在不同内存区域进行独立的内存管理。

🎯 学习目标

  • 掌握默认堆的初始化与内存区域添加方法
  • 熟练使用 os_malloc、os_free、os_realloc、os_calloc 等默认堆 API
  • 理解多堆机制，能创建和管理自定义堆实例
  • 掌握堆内存统计信息的获取方法
  • 了解堆完整性检查功能

一、堆内存概念

1.1 什么是堆

堆是一块由操作系统管理的内存区域，程序可以在运行时从该区域动态申请和释放任意大小的内存块。与栈（Stack）不同，堆内存的生命周期由程序员显式控制，不受函数调用栈的限制。

1.2 OneOS 堆架构

OneOS 的堆内存管理采用分层架构：

1.3 堆控制块（os_heap_t）字段详解

堆的控制块 os_heap_t（即 struct os_heap）定义在 kernel/source/os_prototypes.h 中：

来源：kernel/source/os_prototypes.h

struct os_heap
{
    struct heap_mem *h_mem;
    uint8_t          object_inited;
    char             name[OS_NAME_MAX + 1];
    os_list_node_t   resource_node; /* Node in resource list */
};
typedef struct os_heap os_heap_t;

各字段含义如下：

字段类型说明
h_memstruct heap_mem *内存区域链表头：指向该堆的第一个内存区域（heap_mem），一个堆可有多个内存区域
object_initeduint8_t是否已初始化（OS_KOBJ_INITED / OS_KOBJ_DEINITED）
namechar[OS_NAME_MAX+1]堆名称（调试/Shell 显示用）
resource_nodeos_list_node_t资源链表节点，把堆挂到全局堆资源链表（防重复创建/系统查询）

概念对应表：

堆概念对应字段
堆包含的内存区域h_mem（指向第一个 heap_mem）
生命周期object_inited
堆标识name
系统管理/防重复resource_node（挂到 gs_os_heap_resource_list_head）

关键点：os_heap_t 是堆的顶层控制块，但它不直接存内存块——真正管理内存块的是它指向的 h_mem（heap_mem 内存区域对象）。一个堆通过 os_heap_add 可挂多个内存区域（h_mem 链表）。

1.4 内存区域控制块（struct heap_mem）字段详解

每个堆可包含多个内存区域，每个区域由一个 struct heap_mem 描述，定义在 kernel/source/os_prototypes.h 中：

来源：kernel/source/os_prototypes.h

各字段含义如下：

字段类型说明
k_alloc函数指针该区域算法的分配函数（如 FIRSTFIT 的 k_firstfit_alloc）
k_aligned_alloc函数指针该区域算法的对齐分配函数
k_free函数指针该区域算法的释放函数
k_realloc函数指针该区域算法的重分配函数
k_deinit函数指针该区域算法的反初始化函数
k_mem_check函数指针该区域算法的完整性检查函数
k_mem_trace函数指针内存追踪函数（仅 OS_USING_MEM_TRACE 时存在）
k_ptr_to_size函数指针根据指针返回原块大小（os_heap_realloc 用）
headervoid *该内存区域的起始地址（对齐后）
nextstruct heap_mem *下一个内存区域指针（链接同堆的多个区域）
mem_totalos_size_t该区域总大小（字节）
mem_usedos_size_t该区域已用大小（字节）
mem_maxusedos_size_t该区域历史峰值（字节）
sem_iddummy_semaphore_t该区域并发保护的信号量
algenum os_mem_alg该区域使用的内存算法（FIRSTFIT/BUDDY）

概念对应表：

内存区域概念对应字段
区域起始地址header
区域大小mem_total
已用/峰值mem_used / mem_maxused
同堆下一个区域next
区域算法alg
区域并发保护sem_id
算法操作接口k_alloc/k_free/k_realloc/k_mem_check 等函数指针

关键点 —— 字段与多堆 API 的对应：

  • os_heap_add 用 alg 查 alg_init_table，调用对应算法的 mem_init 把该区域的 k_alloc/k_free 等函数指针绑定到具体算法实现（如 FIRSTFIT）。
  • os_heap_alloc 遍历 h_mem 链表，调用每个区域的 k_alloc——函数指针多态让统一接口支持不同算法。
  • header/next 把同一堆的多个内存区域串成链表（os_heap_add 尾接）。

二、配置依赖

使用堆内存管理需要以下配置。约束来自项目源码 kernel/include/os_memory.h 的编译检查（与项目一致）：

#ifdef OS_USING_HEAP

#ifndef OS_USING_SEMAPHORE
#error "Macro OS_USING_SEMAPHORE must be set."
#endif

#if !defined(OS_USING_ALG_FIRSTFIT) && !defined(OS_USING_ALG_BUDDY)
#error "ERROR! At least one memory algorithm must be choose."
#endif

配置项说明：

配置宏是否必须说明
OS_USING_HEAP必须启用堆内存管理，编译进默认堆 + 多堆代码
OS_USING_SEMAPHORE必须未定义时编译报错 Macro OS_USING_SEMAPHORE must be set（堆并发保护依赖信号量）
OS_USING_ALG_FIRSTFIT至少选其一FIRSTFIT 内存算法
OS_USING_ALG_BUDDY至少选其一BUDDY 内存算法
OS_USING_MEM_TRACE可选内存追踪（泄漏检测），额外提供 os_default_heap_trace()/os_heap_trace()
OS_USING_SHELL可选提供 show_mem/show_heap/check_mem/trace_mem Shell 命令

关键点：OS_USING_HEAP、OS_USING_SEMAPHORE、OS_USING_ALG_* 三者是硬约束——不满足会在编译期 #error。这保证了堆实现依赖的信号量、算法一定存在。

三、堆内存关键宏定义

堆内存实现和 API 中使用了多个宏，理解它们有助于看懂后续的源码分步详解。这些宏分布在不同的头文件中，集中讲解如下。

3.1 OS_HEAP_DEFINE(name) —— 定义堆控制块变量

来源：kernel/include/os_memory.h

#define OS_HEAP_DEFINE(name) os_heap_dummy_t name
  • 展开为一条变量声明：os_heap_dummy_t name。
  • os_heap_dummy_t 是给用户看的占位类型（typedef struct dummy_heap），内存布局与内核真正的 os_heap_t 一致。
  • 用于静态定义一个堆控制块变量（默认堆的 gs_default_heap_control_block、用户多堆的自定义控制块都由此宏产生）。
  • 用法示例：
OS_HEAP_DEFINE(g_my_heap);   /* 展开为：os_heap_dummy_t g_my_heap; */

3.2 OS_TYPE_CONVERT(type, obj) —— 类型转换

来源：kernel/source/os_kernel_internal.h

#define OS_TYPE_CONVERT(type, obj) ((type)(obj))
  • 本质是 C 语言的强转：((type)(obj))。
  • 用于把用户侧占位类型（如 os_heap_dummy_t *）转换为内核真实类型（如 os_heap_t *）。
  • 示例（os_heap_init 中）：
heap = OS_TYPE_CONVERT(os_heap_t *, heap_cb);   /* 等价于 (os_heap_t *)heap_cb */
  • 也用于返回值的类型转换，如 return OS_TYPE_CONVERT(os_heap_id, heap)（把 os_heap_t* 转成 os_heap_id 句柄）。

3.3 OS_ALIGN_UP(size, align) —— 向上对齐

来源：kernel/include/os_stddef.h

/* Return the most contiguous size aligned at specified width. OS_ALIGN_UP(13, 4) would return 16. */
#define OS_ALIGN_UP(size, align) (((size) + (align)-1) & ~((align)-1))
  • 把 size 向上取整到 align 的整数倍。
  • 原理：(size + align - 1) & ~(align - 1)——先加 align-1 再按 align 边界掩码取整（要求 align 为 2 的幂）。

具体演算（OS_ALIGN_UP(13, 4)）：

步骤值说明
size13 = 0b1101原始大小
align - 13 = 0b0011掩码
size + align - 116 = 0b10000加 align-1
~(align - 1)0b...1100按 align 边界掩码
16 & 0b...110016 = 0b10000结果为 16

用途：os_heap_add 里 start = OS_ALIGN_UP(start_addr, OS_ALIGN_SIZE)——把内存区域起始地址向上对齐。

3.4 OS_ALIGN_DOWN(size, align) —— 向下对齐

来源：kernel/include/os_stddef.h

/* Return the down number of aligned at specified width. OS_ALIGN_DOWN(13, 4) would return 12. */
#define OS_ALIGN_DOWN(size, align) ((size) & ~((align)-1))
  • 把 size 向下取整到 align 的整数倍。
  • 原理：size & ~(align - 1)——直接按 align 边界掩码截断低位（要求 align 为 2 的幂）。

具体演算（OS_ALIGN_DOWN(13, 4)）：

步骤值说明
size13 = 0b1101原始大小
~(align - 1)0b...1100按 align 边界掩码
13 & 0b...110012 = 0b1100结果为 12

用途：os_heap_add 里 size = OS_ALIGN_DOWN(start_addr + size - start, OS_ALIGN_SIZE)——把对齐后的区域大小向下取整到对齐边界。

3.5 内存算法枚举 enum os_mem_alg —— 选择堆内存算法

来源：kernel/include/os_dummy.h

各枚举值含义：

枚举值说明
OS_MEM_ALG_FIRSTFIT首次适应算法（仅当配置 OS_USING_ALG_FIRSTFIT 时存在）
OS_MEM_ALG_BUDDY伙伴算法（仅当配置 OS_USING_ALG_BUDDY 时存在）
OS_MEM_ALG_DEFAULT默认算法，实际指向第一个注册的算法（值恒为最后一个）

关键点：

  • 枚举值依赖配置宏——未启用某算法则对应枚举不存在。
  • OS_MEM_ALG_DEFAULT 始终存在，且排在最后；os_heap_add 中 if (OS_MEM_ALG_DEFAULT == alg) alg = (enum os_mem_alg)0 把它转为第一个算法（通常是 FIRSTFIT）。
  • alg_init_table（算法注册表）按配置顺序初始化，os_heap_add 遍历该表找到 alg 对应算法并调用其 mem_init。

这些宏与源码的对应关系：

宏/枚举用在哪段源码
OS_HEAP_DEFINE定义默认堆控制块、用户多堆控制块
OS_TYPE_CONVERTos_heap_init/os_heap_add 等的参数和返回值转换
OS_ALIGN_UPos_heap_add 对齐起始地址
OS_ALIGN_DOWNos_heap_add 对齐区域大小
OS_MEM_ALG_*os_heap_add 选择算法、os_malloc 等

四、默认堆 API

默认堆是 OneOS 提供的一个全局堆实例，其 API 风格与标准 C 库类似，使用最为便捷。所有 API 定义在 kernel/include/os_memory.h 中。

4.1 初始化默认堆

void os_default_heap_init(void);
参数说明
返回值无
  • 功能：初始化默认堆控制块，创建名为 "DEFAULT_HEAP" 的堆实例
  • 调用时机：在系统启动阶段，添加内存区域之前调用
  • 注意：此函数只初始化控制块，不分配实际内存区域

完整源码（kernel/source/os_memory.c，与项目一致）：

void os_default_heap_init(void)
{
    (void)memset(&gs_default_heap_control_block, 0, sizeof(os_heap_dummy_t));
    gs_default_heap = os_heap_init(&gs_default_heap_control_block, "DEFAULT_HEAP");
    if (!gs_default_heap)
    {
        OS_KERN_LOG(KERN_ERROR, MEM_TAG, "default memory heap init failed!");
    }
}

分步详解：

第一步：清零默认堆控制块（无条件执行）

    (void)memset(&gs_default_heap_control_block, 0, sizeof(os_heap_dummy_t));

进入本步的条件：调用 os_default_heap_init() 时无条件执行。把静态定义的默认堆控制块 gs_default_heap_control_block 清零，为复用做准备（gs_default_heap_control_block 是 OS_HEAP_DEFINE(gs_default_heap_control_block) 定义的静态变量）。

第二步：初始化默认堆（无条件执行）—— 调用 os_heap_init

    gs_default_heap = os_heap_init(&gs_default_heap_control_block, "DEFAULT_HEAP");
    if (!gs_default_heap)
    {
        OS_KERN_LOG(KERN_ERROR, MEM_TAG, "default memory heap init failed!");
    }

进入本步的条件：第一步完成。

  • os_heap_init(&gs_default_heap_control_block, "DEFAULT_HEAP")：创建名为 "DEFAULT_HEAP" 的堆实例，返回堆 ID 存入全局 gs_default_heap（os_heap_init 详解见 6.2）。
  • 子分支：条件 gs_default_heap == OS_NULL（初始化失败，如控制块已在资源链表）→ 打印错误日志 default memory heap init failed!。

关键点：os_default_heap_init 只初始化控制块、不添加实际内存。真正的内存区域由 os_default_heap_add 在之后添加。默认堆的控制块是静态全局变量，不动态分配。

4.2 添加内存区域

os_err_t os_default_heap_add(void *start_addr, os_size_t size, enum os_mem_alg alg);
参数类型说明
start_addrvoid *内存区域的起始地址
sizeos_size_t内存区域大小（字节）
algenum os_mem_alg内存管理算法，可选 OS_MEM_ALG_FIRSTFIT、OS_MEM_ALG_BUDDY 或 OS_MEM_ALG_DEFAULT
返回值说明
OS_SUCCESS添加成功
OS_INVAL参数无效或内存区域重叠
OS_NOMEM内存区域太小
  • 功能：向默认堆添加一块可用内存区域，可以多次调用以组合多个不连续的内存区域
  • 注意：OS_MEM_ALG_DEFAULT 会使用配置表中第一个注册的算法（即 OS_MEM_ALG_FIRSTFIT 或 OS_MEM_ALG_BUDDY）

完整源码（kernel/source/os_memory.c，与项目一致）：

os_err_t os_default_heap_add(void *start_addr, os_size_t size, enum os_mem_alg alg)
{
    return os_heap_add(gs_default_heap, start_addr, size, alg);
}

分步详解：

第一步：转发到多堆 API（无条件执行）—— 调用 os_heap_add

    return os_heap_add(gs_default_heap, start_addr, size, alg);

进入本步的条件：调用 os_default_heap_add() 时无条件执行。它只是 os_heap_add 的封装，把堆 ID 固定为默认堆 gs_default_heap，其余参数原样转发。完整实现和分步详解见 6.3 os_heap_add。

关键点：os_default_heap_add 与 os_heap_add 功能完全相同，区别仅在于操作的堆实例——前者固定操作默认堆 gs_default_heap，后者通过 heap_id 指定任意堆。理解 os_heap_add 即理解 os_default_heap_add。

4.3 分配内存

os_malloc() —— 从默认堆分配内存

void *os_malloc(os_size_t size);
参数说明
size请求的内存大小（字节）
返回值成功返回内存指针，失败返回 OS_NULL
  • 功能：从默认堆中分配 size 字节的内存
  • 注意：分配的内存内容是未初始化的

完整源码（kernel/source/os_memory.c，与项目一致）：

void *os_malloc(os_size_t size)
{
    return os_heap_alloc(gs_default_heap, size);
}

分步详解：

第一步：转发到多堆 API（无条件执行）—— 调用 os_heap_alloc

    return os_heap_alloc(gs_default_heap, size);

进入本步的条件：调用 os_malloc() 时无条件执行。os_malloc 只是 os_heap_alloc 的封装，把堆 ID 固定为默认堆 gs_default_heap。完整实现见 6.4 os_heap_alloc（遍历堆的内存区域，逐个尝试算法分配）。

关键点：os_malloc 等价于标准 C 的 malloc，但分配的是 OneOS 默认堆的内存。失败返回 OS_NULL（不抛异常），调用方必须检查返回值。

os_aligned_malloc() —— 分配对齐内存

void *os_aligned_malloc(os_size_t align, os_size_t size);
参数说明
align对齐字节数，必须是 2 的幂
size请求的内存大小（字节）
返回值成功返回对齐后的内存指针，失败返回 OS_NULL
  • 功能：从默认堆中分配内存，返回地址按 align 字节对齐

完整源码（kernel/source/os_memory.c，与项目一致）：

void *os_aligned_malloc(os_size_t align, os_size_t size)
{
    return os_heap_aligned_alloc(gs_default_heap, align, size);
}

分步详解：

第一步：转发到多堆 API（无条件执行）—— 调用 os_heap_aligned_alloc

    return os_heap_aligned_alloc(gs_default_heap, align, size);

进入本步的条件：调用 os_aligned_malloc() 时无条件执行。os_aligned_malloc 只是 os_heap_aligned_alloc 的封装，堆 ID 固定为默认堆。完整实现见 6.4（遍历内存区域调用 k_aligned_alloc 算法分配对齐内存）。

关键点：适合需要特定对齐的场景（如 DMA 缓冲区）。align 必须是 2 的幂，否则对齐行为不确定。

os_calloc() —— 分配并清零内存

void *os_calloc(os_size_t count, os_size_t size);
参数说明
count元素个数
size每个元素大小（字节）
返回值成功返回内存指针，失败返回 OS_NULL
  • 功能：分配 count * size 字节的内存，并将内存初始化为零

完整源码（kernel/source/os_memory.c，与项目一致）：

分步详解：

第一步：分配内存（无条件执行）—— 调用 os_heap_alloc

    void *ptr;

    ptr = os_heap_alloc(gs_default_heap, count * size);

进入本步的条件：调用 os_calloc() 时无条件执行。os_heap_alloc(gs_default_heap, count * size) 从默认堆分配 count * size 字节，返回指针 ptr。

第二步：分配成功则清零（条件：ptr != OS_NULL）—— memset 置零

    if (ptr)
    {
        (void)memset(ptr, 0, count * size);
    }
    return ptr;

进入本步的条件：第一步返回的 ptr != OS_NULL（分配成功）。

  • 子分支 A：条件 ptr != OS_NULL → memset(ptr, 0, count * size) 把内存清零。
  • 子分支 B：条件 ptr == OS_NULL（分配失败）→ 跳过清零，直接返回 OS_NULL。

关键点：os_calloc = os_malloc(count*size) + memset 0。与标准 calloc 一致，适合需要零初始化数组的场景。

4.4 释放内存

void os_free(void *ptr);
参数说明
ptr要释放的内存指针
返回值无
  • 功能：释放之前通过 os_malloc、os_realloc、os_calloc 或 os_aligned_malloc 分配的内存
  • 注意：释放后指针不再有效，不应继续使用

完整源码（kernel/source/os_memory.c，与项目一致）：

void os_free(void *ptr)
{
    os_heap_free(gs_default_heap, ptr);
}

分步详解：

第一步：转发到多堆 API（无条件执行）—— 调用 os_heap_free

    os_heap_free(gs_default_heap, ptr);

进入本步的条件：调用 os_free() 时无条件执行。os_free 只是 os_heap_free 的封装，堆 ID 固定为默认堆。完整实现见 6.4 os_heap_free（遍历内存区域，找到 ptr 所属区域并调用 k_free 释放）。

关键点：ptr 必须是由 OneOS 堆 API 分配的有效指针。释放非法/重复/未由堆分配的指针会触发 OS_ASSERT_EX 断言（见 6.4 os_heap_free）。释放后指针置为悬空，不应再使用。

4.5 重分配内存

void *os_realloc(void *ptr, os_size_t size);
参数说明
ptr原内存指针（若为 OS_NULL，行为等同于 os_malloc）
size新的大小（字节），若为 0，行为等同于 os_free
返回值成功返回新内存指针，失败返回 OS_NULL（原内存保持不变）
  • 功能：调整已分配内存块的大小
  • 注意：重分配可能移动内存位置，返回的指针可能与原指针不同

完整源码（kernel/source/os_memory.c，与项目一致）：

void *os_realloc(void *ptr, os_size_t size)
{
    return os_heap_realloc(gs_default_heap, ptr, size);
}

分步详解：

第一步：转发到多堆 API（无条件执行）—— 调用 os_heap_realloc

    return os_heap_realloc(gs_default_heap, ptr, size);

进入本步的条件：调用 os_realloc() 时无条件执行。os_realloc 只是 os_heap_realloc 的封装，堆 ID 固定为默认堆。完整实现见 6.4 os_heap_realloc（若 ptr 为 OS_NULL 则等同分配；否则在所属区域重分配；原区域失败则尝试其他区域并拷贝）。

关键点：os_realloc 兼容三种语义——ptr==OS_NULL 时等同 os_malloc(size)、size==0 时等同 os_free(ptr)、否则调整大小。失败时返回 OS_NULL 且原内存保持不变。

4.6 获取堆信息

void os_default_heap_info(os_meminfo_t *info);
参数说明
info指向 os_meminfo_t 结构体的指针，用于接收统计信息
返回值无
  • 功能：获取默认堆的统计信息（总大小/已用/峰值）

完整源码（kernel/source/os_memory.c，与项目一致）：

void os_default_heap_info(os_meminfo_t *info)
{
    OS_ASSERT(info);
    os_heap_info(gs_default_heap, info);
}

分步详解：

第一步：参数校验（条件：info != OS_NULL）—— 不满足则断言崩溃

    OS_ASSERT(info);

进入本步的条件：调用 os_default_heap_info() 时无条件执行。info 是传出参数（函数要写它），必须非空。

第二步：转发到多堆 API（无条件执行）—— 调用 os_heap_info

    os_heap_info(gs_default_heap, info);

进入本步的条件：第一步断言通过。os_heap_info 遍历默认堆所有内存区域，累加 mem_total/mem_used/mem_maxused 到 info（完整实现见 6.4）。

4.7 堆完整性检查

os_err_t os_default_heap_check(void);
参数说明
返回值OS_SUCCESS 表示堆正常，其他值表示发现错误
  • 功能：检查默认堆的完整性，验证所有内存块的数据结构是否一致

完整源码（kernel/source/os_memory.c，与项目一致）：

os_err_t os_default_heap_check(void)
{
    return os_heap_check(gs_default_heap);
}

分步详解：

第一步：转发到多堆 API（无条件执行）—— 调用 os_heap_check

    return os_heap_check(gs_default_heap);

进入本步的条件：调用 os_default_heap_check() 时无条件执行。os_default_heap_check 只是 os_heap_check 的封装，堆 ID 固定为默认堆。完整实现见 6.4 os_heap_check（遍历内存区域，调用 k_mem_check 校验每个区域的数据结构一致性）。

关键点：堆完整性检查用于调试内存越界/损坏——检测内存块的头部/尾部标记是否被改写。若返回非 OS_SUCCESS，说明堆被破坏，通常是缓冲区越界或野指针写入导致。

五、默认堆使用示例

六、多堆管理

除了默认堆，OneOS 还支持创建多个自定义堆实例，适用于需要将不同内存区域独立管理的场景（例如：将 SRAM 和 SDRAM 分别作为独立的堆来管理）。

6.1 静态定义堆

#define OS_HEAP_DEFINE(name) os_heap_dummy_t name
  • 功能：静态定义一个堆控制块变量
  • 示例：OS_HEAP_DEFINE(my_sdram_heap); 定义一个名为 my_sdram_heap 的堆控制块

宏定义详解（kernel/include/os_memory.h，与项目一致）：

#define OS_HEAP_DEFINE(name) os_heap_dummy_t name
  • 展开为一条变量声明：os_heap_dummy_t name。
  • os_heap_dummy_t 是给用户看的占位类型（typedef struct dummy_heap），内存布局与内核真正的 os_heap_t 一致。
  • 用户用它定义一个全局变量 name，这块静态内存将来被内核当作堆控制块使用。

关键点：静态定义的堆控制块是静态内存，不依赖 OS_USING_HEAP 之外的动态分配。多堆的每个堆都需要一个独立的 OS_HEAP_DEFINE 变量。

6.2 创建堆

os_heap_id os_heap_init(os_heap_dummy_t *heap_cb, const char *name);
参数类型说明
heap_cbos_heap_dummy_t *静态定义的堆控制块指针
nameconst char *堆名称（用于调试和 Shell 显示）
返回值说明
os_heap_id堆实例 ID，非空表示成功
OS_NULL创建失败（堆已存在）

完整源码（kernel/source/os_memory.c，与项目一致）：

分步详解：

第一步：准备与参数校验（条件：heap_cb 非空）—— 不满足则断言崩溃

    heap = OS_TYPE_CONVERT(os_heap_t *, heap_cb);

    OS_ASSERT(heap);
    ret = OS_SUCCESS;

进入本步的条件：调用 os_heap_init() 时无条件执行。heap_cb 经强转后必须非空（用户传入的静态控制块）。

第二步：防重复创建检查（条件：资源链表遍历）—— 已存在则返回 OS_INVAL

进入本步的条件：第一步断言通过。加堆资源链表锁 gs_os_heap_resource_list_lock，遍历整个堆资源链表。

  • 子分支：条件 item_heap == heap（发现同一控制块地址已创建过，即重复创建）→ 释放锁、打日志 The heap already exist、ret = OS_INVAL、heap = OS_NULL，break。

为什么需防重复：堆控制块由用户静态提供、地址固定。同一个 heap_cb 地址被 os_heap_init 两次，会重复登记进资源链表、重复初始化同一块内存，造成链表错乱。

第三步：登记并初始化（条件：未重复创建，ret == OS_SUCCESS）—— 登记链表 + 复制名称 + 初始化字段

进入本步的条件：第二步未发现重复（ret == OS_SUCCESS）。

  • os_list_add_tail(...)：把堆的 resource_node 登记进堆资源链表。
  • 子分支：条件 name != OS_NULL → strncpy 复制名称（最多 OS_NAME_MAX 字符，末尾补 '\0'）；否则（name == OS_NULL）→ name[0] = '\0'（空名）。
  • h_mem = OS_NULL：初始无内存区域。
  • object_inited = OS_KOBJ_INITED：标记已初始化。

最终返回值：return OS_TYPE_CONVERT(os_heap_id, heap)——成功返回堆 ID；重复创建时 heap == OS_NULL，返回 OS_NULL。

6.3 添加内存区域

os_err_t os_heap_add(os_heap_id heap_id, void *start_addr, os_size_t size, enum os_mem_alg alg);
参数类型说明
heap_idos_heap_id堆实例 ID
start_addrvoid *内存区域起始地址
sizeos_size_t内存区域大小（字节）
algenum os_mem_alg内存管理算法
返回值说明
OS_SUCCESS添加成功
OS_INVAL参数无效或内存区域重叠
OS_NOMEM内存区域太小

参数与 os_default_heap_add 相同，但需要指定 heap_id。

完整源码（kernel/source/os_memory.c，与项目一致）：

分步详解：

第一步：准备与参数校验（条件：堆非空/已初始化/算法合法）—— 不满足则断言崩溃

进入本步的条件：调用 os_heap_add() 时无条件执行（入口硬性校验）。

  • heap != OS_NULL、object_inited == OS_KOBJ_INITED：堆已初始化。
  • alg <= OS_MEM_ALG_DEFAULT：算法合法。
  • 子条件：alg == OS_MEM_ALG_DEFAULT → 把算法改为 (enum os_mem_alg)0（即 OS_MEM_ALG_FIRSTFIT，因为 alg_init_table 第一个注册的通常是 FIRSTFIT）。

第二步：对齐起始地址和大小（无条件执行）—— 地址对齐 + 大小对齐

    ret   = OS_SUCCESS;
    start = OS_ALIGN_UP((os_size_t)(char *)start_addr, OS_ALIGN_SIZE);
    OS_ASSERT(((os_size_t)(char *)start_addr + size) > start);
    size = OS_ALIGN_DOWN((os_size_t)(char *)start_addr + size - start, OS_ALIGN_SIZE);

进入本步的条件：第一步断言通过。

  • start = OS_ALIGN_UP(start_addr, OS_ALIGN_SIZE)：起始地址向上对齐到对齐边界。
  • OS_ASSERT((start_addr + size) > start)：校验对齐后地址不越界（防起始地址+大小溢出）。
  • size = OS_ALIGN_DOWN(start_addr + size - start, OS_ALIGN_SIZE)：对齐后的内存区域大小（去掉对齐损失，向下取整到对齐边界）。

第三步：检查内存区域是否重叠（条件：size > sizeof(struct heap_mem)）—— 重叠则返回 OS_INVAL，太小返回 OS_NOMEM

进入本步的条件：第二步完成。size > sizeof(struct heap_mem)（对齐后大小能容纳一个堆管理头 heap_mem）。

  • 加堆资源链表锁，遍历所有堆的所有内存区域：
    • 计算每个已存在区域的范围 [h_mem_temp_start, h_mem_temp_end)；
    • 条件 start >= h_mem_temp_end || h_mem_temp_start >= start+size（新区间与旧区间不重叠）→ 继续检查下一个；
    • 否则（重叠）→ 打日志 memory is overlaped，ret = OS_INVAL，break。
  • 条件 size <= sizeof(struct heap_mem)（区域太小，连管理头都放不下）→ ret = OS_NOMEM。

第四步：调用算法初始化内存区域（条件：ret == OS_SUCCESS）—— 查找算法并初始化

进入本步的条件：第三步未发现重叠/太小（ret == OS_SUCCESS）。

  • 把 start 处作为 h_mem_new（新内存区域管理头），清零，start 前进一个 heap_mem 头大小、size 减去头大小。
  • 遍历算法注册表 alg_init_table：
    • 条件 alg == alg_init_table[i].mem_alg → 调用对应算法的 mem_init（如 k_firstfit_mem_init）初始化该区域，mem_inited = OS_TRUE，break。

第五步：挂接到堆的内存区域链表（条件：算法初始化成功）—— 头插或尾接

进入本步的条件：第四步完成。

  • 子分支 A：条件 mem_inited == OS_TRUE（算法初始化成功）：
    • 条件 heap->h_mem != OS_NULL（已有内存区域）→ 遍历到链表末尾，把 h_mem_new 接到尾部（一个堆可组合多个内存区域）；
    • 条件 heap->h_mem == OS_NULL（首个区域）→ heap->h_mem = h_mem_new。
  • 子分支 B：条件 mem_inited == OS_FALSE（算法未找到）→ 打日志 memory algorithm not support，ret = OS_INVAL。
  • 释放锁。

os_heap_add 的 if-else 条件走向总结：

6.4 多堆分配与释放

void *os_heap_alloc(os_heap_id heap_id, os_size_t size);
void *os_heap_aligned_alloc(os_heap_id heap_id, os_size_t align, os_size_t size);
void  os_heap_free(os_heap_id heap_id, void *ptr);
void *os_heap_realloc(os_heap_id heap_id, void *ptr, os_size_t size);
void  os_heap_info(os_heap_id heap_id, os_meminfo_t *info);
os_err_t os_heap_check(os_heap_id heap_id);

这些 API 与默认堆 API 功能相同，但需要指定 heap_id 来操作特定的堆实例。

os_heap_alloc() —— 从指定堆分配内存

完整源码（kernel/source/os_memory.c，与项目一致）：

分步详解：

第一步：参数校验（条件：堆非空/已初始化）—— 不满足则断言崩溃

    OS_ASSERT(heap);
    OS_ASSERT(OS_KOBJ_INITED == heap->object_inited);

进入本步的条件：调用 os_heap_alloc() 时无条件执行。堆非空、已初始化。

第二步：遍历内存区域逐个尝试分配（条件：存在 h_mem 且支持 k_alloc）—— 任一成功即返回

进入本步的条件：第一步断言通过。

  • 条件 h_mem != OS_NULL 且 h_mem->k_alloc != OS_NULL（有内存区域且该区域算法支持分配）→ 调用 h_mem->k_alloc(h_mem, size) 尝试分配。
  • 子分支：条件 ptr != OS_NULL（该区域分配成功）→ break 返回；
  • 否则（该区域内存不足）→ h_mem = h_mem->next 尝试下一个内存区域。
  • 全部区域都失败 → 返回 OS_NULL。

关键点：一个堆可有多个内存区域（os_heap_add 多次添加），分配时依次尝试每个区域，任一区域成功即可。这是多区域堆的实现方式。

os_heap_aligned_alloc() —— 从指定堆分配对齐内存

完整源码（kernel/source/os_memory.c，与项目一致）：

分步详解：

第一步：参数校验（条件：堆非空/已初始化）—— 不满足则断言崩溃

    OS_ASSERT(heap);
    OS_ASSERT(OS_KOBJ_INITED == heap->object_inited);

进入本步的条件：调用 os_heap_aligned_alloc() 时无条件执行。堆非空、已初始化。

第二步：遍历内存区域尝试对齐分配（条件：存在 h_mem 且支持 k_aligned_alloc）

进入本步的条件：第一步断言通过。与 os_heap_alloc 逻辑相同，但调用每个区域的 k_aligned_alloc(h_mem, align, size) 进行对齐分配（align 必须为 2 的幂）。

os_heap_free() —— 从指定堆释放内存

完整源码（kernel/source/os_memory.c，与项目一致）：

分步详解：

第一步：参数校验（条件：堆非空/已初始化/ptr 非空）—— 不满足则断言崩溃

    OS_ASSERT(heap);
    OS_ASSERT(OS_KOBJ_INITED == heap->object_inited);
    OS_ASSERT(ptr);

进入本步的条件：调用 os_heap_free() 时无条件执行。堆非空、已初始化、ptr 非空。

第二步：定位 ptr 所属内存区域并释放（条件：找到 ptr 在哪个 h_mem 范围内）

进入本步的条件：第一步断言通过。

  • 遍历堆的内存区域，条件 ptr 落在该区域 [header, header+mem_total] 内 → 调用 h_mem->k_free(h_mem, ptr) 释放该区域内的块，break。
  • 遍历完未找到（h_mem == OS_NULL，ptr 不是本堆分配的内存）→ OS_ASSERT_EX 断言崩溃。

关键点：os_heap_free 不能释放不是本堆分配的指针——ptr 必须来自 os_heap_alloc/os_heap_aligned_alloc 等本堆分配函数，否则触发断言。

os_heap_realloc() —— 重分配指定堆内存

完整源码（kernel/source/os_memory.c，与项目一致）：

分步详解：

第一步：参数校验（条件：堆非空/已初始化）—— 不满足则断言崩溃

    OS_ASSERT(heap);
    OS_ASSERT(OS_KOBJ_INITED == heap->object_inited);

进入本步的条件：调用 os_heap_realloc() 时无条件执行。堆非空、已初始化。

第二步：ptr 为空则直接分配（条件：ptr == OS_NULL）—— 等同 os_heap_alloc

    if (!ptr)
    {
        ptr_new = os_heap_alloc((os_heap_id)heap, size);
    }

进入本步的条件：ptr == OS_NULL（无原内存块）→ os_heap_alloc 直接分配 size 字节，ptr_new = 分配结果（等同 malloc 语义）。

第三步：在所属内存区域重分配（条件：ptr != OS_NULL）—— 查找原区域并重分配

进入本步的条件：ptr != OS_NULL（有原内存块）。

  • 遍历内存区域，找到 ptr 所属的 h_mem。
  • 条件 h_mem 存在且支持 k_realloc → 调用 h_mem->k_realloc(h_mem, ptr, size) 在原区域尝试调整大小，结果存 ptr_new。
  • 找不到 h_mem（ptr 不是本堆的）→ OS_ASSERT_EX 断言崩溃。

第四步：原区域失败则迁移到其他区域（条件：ptr_new == OS_NULL 且原区域支持释放）—— 拷贝并释放原块

进入本步的条件：ptr_new == OS_NULL（原区域重分配失败，如空间不足）且原区域支持释放 k_free。

  • 遍历其他内存区域（h_mem_new != h_mem）尝试 k_alloc；
  • 条件分配成功 → oldsize = k_ptr_to_size 取原块大小，memcpy(ptr_new, ptr, min(oldsize, size)) 拷贝数据，h_mem->k_free 释放原块，break。

关键点：os_heap_realloc 支持三种情况——ptr==NULL（等同 malloc）、在原区域原地重分配、原区域失败则迁移到其他区域并拷贝数据。失败返回 OS_NULL 且原内存不变。

os_heap_info() —— 获取指定堆统计信息

完整源码（kernel/source/os_memory.c，与项目一致）：

分步详解：

第一步：参数校验（条件：堆非空/已初始化/info 非空）—— 不满足则断言崩溃

    OS_ASSERT(heap);
    OS_ASSERT(OS_KOBJ_INITED == heap->object_inited);
    OS_ASSERT(info);

进入本步的条件：调用 os_heap_info() 时无条件执行。info 是传出参数，必须非空。

第二步：清零并累加各区域统计（无条件执行）—— 遍历所有内存区域

进入本步的条件：第一步断言通过。

  • memset(info, 0, ...)：清零 info（防脏数据累加）。
  • 遍历所有内存区域，累加各区域的 mem_total/mem_used/mem_maxused 到 info。

关键点：多区域堆的统计是所有区域累加之和。

os_heap_check() —— 检查指定堆完整性

完整源码（kernel/source/os_memory.c，与项目一致）：

分步详解：

第一步：参数校验（条件：堆非空/已初始化）—— 不满足则断言崩溃

    OS_ASSERT(heap);
    OS_ASSERT(OS_KOBJ_INITED == heap->object_inited);

进入本步的条件：调用 os_heap_check() 时无条件执行。堆非空、已初始化。

第二步：遍历各区域调用算法校验（条件：存在 h_mem 且支持 k_mem_check）—— 任一失败即返回错误

进入本步的条件：第一步断言通过。

  • 遍历内存区域，条件支持 k_mem_check → 调用 h_mem->k_mem_check(h_mem) 校验该区域。
  • 子分支：条件 ret != OS_SUCCESS（某区域校验失败）→ break，直接返回错误。
  • 全部区域正常 → 返回 OS_SUCCESS。

6.5 多堆使用示例

七、Shell 命令

OneOS 提供了 Shell 命令用于调试堆内存：

命令功能说明
show_mem显示默认堆使用情况包括总大小、已用、使用率、峰值、地址范围
show_heap显示所有堆信息遍历所有已注册的堆实例
check_mem检查默认堆完整性验证内存块结构一致性

📝 本节小结

核心要点回顾

本节围绕堆内存管理展开，核心要点如下：

1. 默认堆 API 与标准 C 库的对应关系

OneOS API等价 C 库功能
os_mallocmalloc分配内存
os_calloccalloc分配并清零
os_freefree释放内存
os_reallocrealloc重分配内存
os_aligned_mallocposix_memalign对齐分配

2. 初始化流程（三步）

  • os_default_heap_init()：初始化默认堆控制块（创建 "DEFAULT_HEAP"）。
  • os_default_heap_add()：添加实际内存区域（可多次，组合多区域）。
  • 之后才能用 os_malloc 等分配。

3. 多堆机制

  • 用 OS_HEAP_DEFINE(name) 静态定义堆控制块。
  • os_heap_init 创建堆（有防重复检查），os_heap_add 添加区域。
  • 分配/释放需指定 heap_id（os_heap_alloc/os_heap_free 等）。

4. 分配 API 的内部机制

  • os_heap_alloc 遍历堆的所有内存区域，逐个尝试 k_alloc，任一成功即返回。
  • os_heap_realloc 支持原地重分配、失败则迁移到其他区域并拷贝数据。
  • os_heap_free 需定位 ptr 所属区域再释放，非本堆指针会断言。

5. 配置硬约束

  • OS_USING_HEAP + OS_USING_SEMAPHORE + 至少一种算法（OS_USING_ALG_FIRSTFIT/OS_USING_ALG_BUDDY），不满足编译报 #error。

关键易错点速查

易错点正确做法
os_malloc 返回 OS_NULL 未检查必须检查返回值，否则解引用空指针
未 os_default_heap_init 就分配先初始化控制块，再 os_default_heap_add 添加内存区域
同一个 heap_cb 重复 os_heap_init返回 OS_NULL（防重复检查），应复用已创建的堆
os_heap_add 区域重叠返回 OS_INVAL，应检查区域地址不重叠
os_heap_add 区域太小返回 OS_NOMEM（至少 sizeof(struct heap_mem)）
释放非本堆分配的指针os_heap_free 会断言崩溃，必须释放本堆 os_heap_alloc 返回的指针
os_aligned_malloc 的 align 不是 2 的幂对齐行为不确定，应保证 2 的幂
忽略 os_heap_check 返回值非 OS_SUCCESS 说明堆被破坏（越界/野指针），需排查

下一步

本节掌握了堆内存管理的默认堆与多堆 API。接下来请学习下一小节：

OneOS-Lite 文档 | 学习阁
Copyright © 2026 学习阁