/* ----------------------------------------------------------------------------
 * Copyright (c) Huawei Technologies Co., Ltd. 2013-2020. All rights reserved.
 * Description: LiteOS memory Module Implementation
 * Author: Huawei LiteOS Team
 * Create: 2013-05-12
 * Redistribution and use in source and binary forms, with or without modification,
 * are permitted provided that the following conditions are met:
 * 1. Redistributions of source code must retain the above copyright notice, this list of
 * conditions and the following disclaimer.
 * 2. Redistributions in binary form must reproduce the above copyright notice, this list
 * of conditions and the following disclaimer in the documentation and/or other materials
 * provided with the distribution.
 * 3. Neither the name of the copyright holder nor the names of its contributors may be used
 * to endorse or promote products derived from this software without specific prior written
 * permission.
 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
 * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
 * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
 * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR
 * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
 * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
 * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
 * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
 * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
 * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
 * ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 * --------------------------------------------------------------------------- */

/*
 * @defgroup los_heap Heap
 * @ingroup kernel
 */

#ifndef _LOS_MEMORY_INTERNAL_H
#define _LOS_MEMORY_INTERNAL_H

#include "los_typedef.h"
#include "los_memstat_pri.h"

#ifdef __cplusplus
#if __cplusplus
extern "C" {
#endif /* __cplusplus */
#endif /* __cplusplus */
//用于将指定的大小 sz 进行对齐，返回对齐后的大小。它使用 HEAP_ALIGN 宏定义来指定对齐的字节数，通过将 sz 加上 HEAP_ALIGN - 1，然后按位取反与运算（&）来实现向上对齐。
#define ALIGNE(sz)                            (((sz) + HEAP_ALIGN - 1) & (~(HEAP_ALIGN - 1)))
//用于将指定的 value 进行 align 字节对齐，返回对齐后的值。它将 value 转换为 UINT32 类型，并将其与 align - 1 按位取反与运算，即将 value 向上舍入到最近的 align 的倍数。
#define OS_MEM_ALIGN(value, align)            (((UINT32)(UINTPTR)(value) + (UINT32)((align) - 1)) & \
                                               (~(UINT32)((align) - 1)))
//用于表示对齐标志的宏定义，其值为 0x80000000。
#define OS_MEM_ALIGN_FLAG                     0x80000000
//用于设置对齐标志的宏定义，将传入的 align 参数按位或运算与 OS_MEM_ALIGN_FLAG 进行组合。
#define OS_MEM_SET_ALIGN_FLAG(align)          ((align) = ((align) | OS_MEM_ALIGN_FLAG))
//用于获取对齐标志的宏定义，将传入的 align 参数与 OS_MEM_ALIGN_FLAG 进行按位与运算，得到对齐标志。
#define OS_MEM_GET_ALIGN_FLAG(align)          ((align) & OS_MEM_ALIGN_FLAG)
//用于获取对齐间隙大小的宏定义，将传入的 align 参数与 ~OS_MEM_ALIGN_FLAG 进行按位与运算，得到去除对齐标志后的值。
#define OS_MEM_GET_ALIGN_GAPSIZE(align)       ((align) & (~OS_MEM_ALIGN_FLAG))

typedef struct tagLosHeapStatus {
    UINT32 totalUsedSize;
    UINT32 totalFreeSize;
    UINT32 maxFreeNodeSize;
    UINT32 usedNodeNum;
    UINT32 freeNodeNum;
#ifdef LOSCFG_MEM_TASK_STAT
    UINT32 usageWaterLine;
#endif
} LosHeapStatus;//结构体：描述了内存堆的状态信息，包括总共使用的大小、总共空闲的大小、最大空闲节点的大小、已用节点数和空闲节点数等字段。

/*结构体：描述了内存堆中的每个节点，包括前一个节点指针、任务 ID、节点大小、
是否已经被使用、是否需要对齐等字段。这里使用了位域来节省空间，
并且使用了一个长度为 0 的数组 data[0] 来占位，
方便动态分配内存。*/
struct LosHeapNode {
    struct LosHeapNode *prev;
#ifdef LOSCFG_MEM_TASK_STAT
    UINT32 taskId;
#endif
    UINT32 size     : 30;
    UINT32 used     : 1;
    UINT32 align    : 1;
    UINT8  data[0];
};

extern BOOL OsHeapInit(VOID *pool, UINT32 size);//函数声明：用于初始化内存池，即将一块内存空间转化为一个内存堆，并返回是否初始化成功。
extern VOID* OsHeapAlloc(VOID *pool, UINT32 size);//函数声明：用于在内存堆上分配一块指定大小的内存，并返回分配到的内存地址。
extern VOID* OsHeapAllocAlign(VOID *pool, UINT32 size, UINT32 boundary);//函数声明：用于在内存堆上分配一块指定大小并且按照给定对齐边界对齐的内存，并返回分配到的内存地址。
extern BOOL OsHeapFree(VOID *pool, const VOID* ptr);//函数声明：用于释放内存堆中的指定内存地址所对应的节点，返回是否释放成功。
extern UINT32 OsHeapStatisticsGet(VOID *pool, LosHeapStatus *status);//函数声明：用于获取内存堆的状态信息，并将其保存在传入的 LosHeapStatus 结构体中，返回获取到的信息字节数。
extern UINT32 OsHeapIntegrityCheck(struct LosHeapManager *heap);//函数声明：用于检查整个内存堆的完整性，即检查是否存在内存泄漏或内存重叠等问题。

#ifdef __cplusplus
#if __cplusplus
}
#endif /* __cplusplus */
#endif /* __cplusplus */

#endif /* _LOS_MEMORY_INTERNAL_H */