/* ---------------------------------------------------------------------------- * Copyright (c) Huawei Technologies Co., Ltd. 2013-2019. All rights reserved. * Description: LiteOS memory Module HeadFile * Author: Huawei LiteOS Team * Create: 2013-01-01 * 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_membox Static memory * @ingroup kernel */ #ifndef _LOS_MEMBOX_H #define _LOS_MEMBOX_H #include "los_config.h" #ifdef __cplusplus #if __cplusplus extern "C" { #endif /* __cplusplus */ #endif /* __cplusplus */ /** * @ingroup los_membox * @brief Align the input parameter. * * @par Description: * The macro is used to align memAddr based on UINTPTR. memAddr is the input parameter. * @attention * None. * * @param memAddr [IN] The variable that need to be aligned. Usually memAddr is an unsigned integer * or an unsigned long integer on 64-bit platporm. * * @retval The memAddr value after alignment. * @par Dependency: * * @since Huawei LiteOS V100R001C00 */ #define LOS_MEMBOX_ALLIGNED(memAddr) (((UINTPTR)(memAddr) + sizeof(UINTPTR) - 1) & (~(sizeof(UINTPTR) - 1))) #ifdef LOSCFG_KERNEL_MEMBOX_STATIC /** * @ingroup los_membox * Get next node in static memory pool */ #define OS_MEMBOX_NEXT(addr, blkSize) (LOS_MEMBOX_NODE *)(VOID *)((UINT8 *)(addr) + (blkSize)) /** * @ingroup los_membox * Head size of each node in staic memory pool */ #define OS_MEMBOX_NODE_HEAD_SIZE sizeof(LOS_MEMBOX_NODE) /*LOS_MEMBOX_ALLIGNED(memAddr) 宏用于对内存地址进行对齐操作。 它将 memAddr 强制转换为 UINTPTR 类型，然后加上 sizeof(UINTPTR) - 1，再进行按位取反操作，最后与 ~(sizeof(UINTPTR) - 1) 进行按位与运算。 这样可以确保地址按照 sizeof(UINTPTR) 字节对齐。 OS_MEMBOX_NEXT(addr, blkSize) 宏用于获取静态内存池中下一个节点的地址。 它将 addr 强制转换为 UINT8* 类型，然后加上 blkSize，得到下一个节点的地址。 OS_MEMBOX_NODE_HEAD_SIZE 宏定义了静态内存池中每个节点的头部大小，即 LOS_MEMBOX_NODE 的大小。 这些宏在静态内存池的实现中起到了辅助作用，用于计算和管理内存节点的地址和大小。*/ /** * @ingroup los_membox * @brief Obtain the size of the static memory pool. * * @par Description: * The macro is used to obtain the size of the static memory pool according to the memory * block size and number. * @attention * None. * * @param blkSize [IN] Type #UINT32 The memory block size of the static memory pool. * @param blkNum [IN] Type #UINT32 The total memory block number of the static memory pool. * * @retval The size of the static memory pool. * @par Dependency: * * @since Huawei LiteOS V100R001C00 */ #define LOS_MEMBOX_SIZE(blkSize, blkNum) \ (sizeof(LOS_MEMBOX_INFO) + (LOS_MEMBOX_ALLIGNED((blkSize) + OS_MEMBOX_NODE_HEAD_SIZE) * (blkNum))) /*该宏首先使用 LOS_MEMBOX_ALLIGNED 宏对 (blkSize) + OS_MEMBOX_NODE_HEAD_SIZE 进行对齐操作，确保每个内存块都按照节点大小对齐。然后将对齐后的大小乘以 blkNum，并加上 sizeof(LOS_MEMBOX_INFO)，得到静态内存池的总大小。 其中，sizeof(LOS_MEMBOX_INFO) 表示静态内存池的元信息（头部）大小， 包括内存池起始地址、内存块大小、内存块数量等信息。*/ /** * @ingroup los_membox * Structure of a free node in a static memory pool */ typedef struct tagMEMBOX_NODE { struct tagMEMBOX_NODE *pstNext; /**< Free node's pointer to the next node in a static memory pool. */ } LOS_MEMBOX_NODE; #endif /** * @ingroup los_membox * Static memory pool information structure */ typedef struct { UINT32 uwBlkSize; /**< The memory block size of the static memory pool */ UINT32 uwBlkNum; /**< The total memory block number of the static memory pool */ UINT32 uwBlkCnt; /**< The number of allocated memory blocks in the static memory pool */ #ifdef LOSCFG_KERNEL_MEMBOX_STATIC LOS_MEMBOX_NODE stFreeList; /**< The list of free memory block node in the static memory pool. This structure member is available only LOSCFG_KERNEL_MEMBOX_STATIC is defined. */ #endif } LOS_MEMBOX_INFO; typedef LOS_MEMBOX_INFO OS_MEMBOX_S; /*LOS_MEMBOX_INFO：静态内存池的元信息结构体。包含了静态内存池的起始地址、 内存块大小、内存块数量等信息。同时还包含了 uwBlkCnt 记录已分配内存块数量的成员变量 和 stFreeList 用于记录空闲内存块的链表（仅在 LOSCFG_KERNEL_MEMBOX_STATIC 宏定义时可用）。 OS_MEMBOX_S：与 LOS_MEMBOX_INFO 结构体等价的别名。*/ /** * @ingroup los_membox * @brief Initialize a static memory pool. * * @par Description: * This API is used to initialize a static memory pool. The start address of the memory pool is specified * by the first parameter. In the API, it will set the memory block size, total block number, allocated * block number and the list of free memory block nodes of the static memory pool. * @attention * The poolSize parameter value should match the following two conditions: * * * @param pool [IN] Memory pool address. * @param poolSize [IN] The total size of the static memory pool. * @param blkSize [IN] The memory block size of the static memory pool. * * @retval #LOS_NOK The memory pool fails to be initialized. * @retval #LOS_OK The memory pool is successfully initialized. * @par Dependency: * * @since Huawei LiteOS V100R001C00 */ extern UINT32 LOS_MemboxInit(VOID *pool, UINT32 poolSize, UINT32 blkSize); /*该函数会使用提供的内存池起始地址和大小来初始化静态内存池，并指定每个内存块的大小。 在初始化完成后，该内存池将可以被用于分配内存块。*/ /** * @ingroup los_membox * @brief Request a static memory block. * * @par Description: * This API is used to request a static memory block from the static memory pool which has been initialized. * @attention * The input pool parameter must be initialized via func #LOS_MemboxInit. * * @param pool [IN] Memory pool address. * * @retval #VOID* This API will return a memory block address, if the request is accepted successfully. * @retval #NULL The request fails. * @par Dependency: * * @see LOS_MemboxFree * @since Huawei LiteOS V100R001C00 */ extern VOID *LOS_MemboxAlloc(VOID *pool); /** * @ingroup los_membox * @brief Free a static memory block. * * @par Description: * This API is used to free a static memory block to the static memory pool. * @attention * * * @param pool [IN] Memory pool address. The memory block need to release is requested * from this memory pool. * @param box [IN] The pointer to the memory block to be released. * * @retval #LOS_NOK This memory block fails to be freed. * @retval #LOS_OK This memory block is successfully freed. * @par Dependency: * * @see LOS_MemboxAlloc * @since Huawei LiteOS V100R001C00 */ extern UINT32 LOS_MemboxFree(VOID *pool, VOID *box); /*调用该函数将会释放 box 所指向的内存块，并将其重新加入到内存池的空闲内存块链表中，以便下次分配使用。*/ /** * @ingroup los_membox * @brief Clear a static memory block. * * @par Description: * This API is used to set the memory block value to 0. * @attention * * * @param pool [IN] Memory pool address. The memory block need to clear is requested * from this memory pool. * @param box [IN] The pointer to the memory block to clear. * @retval None. * @par Dependency: * * @since Huawei LiteOS V100R001C00 */ extern VOID LOS_MemboxClr(VOID *pool, VOID *box); /*调用该函数将会将 box 所指向的内存块的数据内容清零，使其变为初始状态。 该函数通常用于在重新使用内存块之前清除其中的旧数据，以免对后续操作产生影响。*/ /** * @ingroup los_membox * @brief show static memory pool information. * * @par Description: * This API is used to print static memory pool information. It can print the memory pool address, * the memory block size, the total block number, the list of free memory block node and the total block * node list of the static memory pool. * @attention * The input pool parameter must be initialized via func #LOS_MemboxInit. * * @param pool [IN] Memory pool address. * * @retval None. * @par Dependency: * * @see LOS_MemboxStatisticsGet * @since Huawei LiteOS V100R001C00 */ extern VOID LOS_ShowBox(VOID *pool); /** * @ingroup los_membox * @brief Obtain the static memory pool information. * * @par Description: * This API is used to obtain the static memory pool information. The information includes * the total memory block number, block size and the allocated block number of the static * memory pool. The obtained information will be outputted in the last three parameters. * * @attention * The first parameter boxMem of this interface is a pointer, it should be a correct value. * Otherwise the system may be abnormal. * * @param boxMem [IN] Type #VOID* Pointer to the static memory pool. * @param maxBlk [OUT] Type #UINT32* The total memory block number is outputted to this parameter. * @param blkCnt [OUT] Type #UINT32* The allocated memory block number is outputted to this parameter. * @param blkSize [OUT] Type #UINT32* The memory block size is outputted to this parameter. * * @retval #LOS_OK Obtain the static memory pool information successfully. * @retval #LOS_NOK Failed to obtain the static memory pool information, check whether the * parameters is NULL or not. * @par Dependency: * * @see LOS_ShowBox * @since Huawei LiteOS V100R001C00 */ extern UINT32 LOS_MemboxStatisticsGet(const VOID *boxMem, UINT32 *maxBlk, UINT32 *blkCnt, UINT32 *blkSize); /*调用该函数将会获取静态内存池的统计信息，包括最大可分配内存块数量、 已分配内存块数量以及每个内存块的大小，并通过传入的指针参数返回给调用者。 这些统计信息可以用于监控和调试内存池的使用情况。*/ #ifdef __cplusplus #if __cplusplus } #endif /* __cplusplus */ #endif /* __cplusplus */ #endif /* _LOS_MEMBOX_H */