更新日期: 2022/06/01 来源: https://gitee.com/weharmony/kernel_liteos_a_note
los_membox.h
浏览该文件的文档.
1/*
2 * Copyright (c) 2013-2019 Huawei Technologies Co., Ltd. All rights reserved.
3 * Copyright (c) 2020-2021 Huawei Device Co., Ltd. All rights reserved.
4 *
5 * Redistribution and use in source and binary forms, with or without modification,
6 * are permitted provided that the following conditions are met:
7 *
8 * 1. Redistributions of source code must retain the above copyright notice, this list of
9 * conditions and the following disclaimer.
10 *
11 * 2. Redistributions in binary form must reproduce the above copyright notice, this list
12 * of conditions and the following disclaimer in the documentation and/or other materials
13 * provided with the distribution.
14 *
15 * 3. Neither the name of the copyright holder nor the names of its contributors may be used
16 * to endorse or promote products derived from this software without specific prior written
17 * permission.
18 *
19 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
20 * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
21 * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
22 * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR
23 * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
24 * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
25 * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
26 * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
27 * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
28 * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
29 * ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
30 */
31
32/**
33 * @defgroup los_membox Static memory
34 * @ingroup kernel
35 */
36
37#ifndef _LOS_MEMBOX_H
38#define _LOS_MEMBOX_H
39
40#include "los_config.h"
41
42#ifdef __cplusplus
43#if __cplusplus
44extern "C" {
45#endif /* __cplusplus */
46#endif /* __cplusplus */
47
48#define OS_MEMBOX_NEXT(addr, blkSize) (LOS_MEMBOX_NODE *)(VOID *)((UINT8 *)(addr) + (blkSize))
49
50#define OS_MEMBOX_NODE_HEAD_SIZE sizeof(LOS_MEMBOX_NODE)
51
52/**
53 * @ingroup los_membox
54 * Structure of a free node in a memory pool
55 */
56typedef struct tagMEMBOX_NODE { //内存池中空闲节点的结构,是个单向的链表
57 struct tagMEMBOX_NODE *pstNext; /**< Free node's pointer to the next node in a memory pool | 指向内存池中下一个空闲节点的指针*/
59
60/**
61 * @ingroup los_membox
62 * Memory pool information structure
63 */
64typedef struct {//静态内存池头结构体
65 UINT32 uwBlkSize; /**< Block size | 块大小*/
66 UINT32 uwBlkNum; /**< Block number | 块数量*/
67 UINT32 uwBlkCnt; /**< The number of allocated blocks | 已经被分配的块数量*/
68 LOS_MEMBOX_NODE stFreeList; /**< Free list | 空闲链表*/
70
72
73/**
74 * @ingroup los_membox
75 * Memory pool alignment
76 */
77#define LOS_MEMBOX_ALIGNED(memAddr) (((UINTPTR)(memAddr) + sizeof(UINTPTR) - 1) & (~(sizeof(UINTPTR) - 1)))
78
79/**
80 * @ingroup los_membox
81 * Memory pool size
82 */
83#define LOS_MEMBOX_SIZE(blkSize, blkNum) \
84 (sizeof(LOS_MEMBOX_INFO) + (LOS_MEMBOX_ALIGNED((blkSize) + OS_MEMBOX_NODE_HEAD_SIZE) * (blkNum)))
85
86/**
87 * @ingroup los_membox
88 * @brief Initialize a memory pool.
89 *
90 * @par Description:
91 * <ul>
92 * <li>This API is used to initialize a memory pool.</li>
93 * </ul>
94 * @attention
95 * <ul>
96 * <li>The poolSize parameter value should match the following two conditions :
97 * 1) Be less than or equal to the Memory pool size;
98 * 2) Be greater than the size of LOS_MEMBOX_INFO.</li>
99 * </ul>
100 *
101 * @param pool [IN] Memory pool address.
102 * @param poolSize [IN] Memory pool size.
103 * @param blkSize [IN] Memory block size.
104 *
105 * @retval #LOS_NOK The memory pool fails to be initialized.
106 * @retval #LOS_OK The memory pool is successfully initialized.
107 * @par Dependency:
108 * <ul>
109 * <li>los_membox.h: the header file that contains the API declaration.</li>
110 * </ul>
111 * @see None.
112 */
113extern UINT32 LOS_MemboxInit(VOID *pool, UINT32 poolSize, UINT32 blkSize);
114
115/**
116 * @ingroup los_membox
117 * @brief Request a memory block.
118 *
119 * @par Description:
120 * <ul>
121 * <li>This API is used to request a memory block.</li>
122 * </ul>
123 * @attention
124 * <ul>
125 * <li>The input pool parameter must be initialized via func LOS_MemboxInit.</li>
126 * </ul>
127 *
128 * @param pool [IN] Memory pool address.
129 *
130 * @retval #VOID* The request is accepted, and return a memory block address.
131 * @retval #NULL The request fails.
132 * @par Dependency:
133 * <ul>
134 * <li>los_membox.h: the header file that contains the API declaration.</li>
135 * </ul>
136 * @see LOS_MemboxFree
137 */
138extern VOID *LOS_MemboxAlloc(VOID *pool);
139
140/**
141 * @ingroup los_membox
142 * @brief Free a memory block.
143 *
144 * @par Description:
145 * <ul>
146 * <li>This API is used to free a memory block.</li>
147 * </ul>
148 * @attention
149 * <ul>
150 * <li>The input pool parameter must be initialized via func LOS_MemboxInit.</li>
151 * <li>The input box parameter must be allocated by LOS_MemboxAlloc.</li>
152 * </ul>
153 *
154 * @param pool [IN] Memory pool address.
155 * @param box [IN] Memory block address.
156 *
157 * @retval #LOS_NOK This memory block fails to be freed.
158 * @retval #LOS_OK This memory block is successfully freed.
159 * @par Dependency:
160 * <ul>
161 * <li>los_membox.h: the header file that contains the API declaration.</li>
162 * </ul>
163 * @see LOS_MemboxAlloc
164 */
165extern UINT32 LOS_MemboxFree(VOID *pool, VOID *box);
166
167/**
168 * @ingroup los_membox
169 * @brief Clear a memory block.
170 *
171 * @par Description:
172 * <ul>
173 * <li>This API is used to set the memory block value to be 0.</li>
174 * </ul>
175 * @attention
176 * <ul>
177 * <li>The input pool parameter must be initialized via func LOS_MemboxInit.</li>
178 * <li>The input box parameter must be allocated by LOS_MemboxAlloc.</li>
179 * </ul>
180 *
181 * @param pool [IN] Memory pool address.
182 * @param box [IN] Memory block address.
183 *
184 * @retval VOID
185 * @par Dependency:
186 * <ul>
187 * <li>los_membox.h: the header file that contains the API declaration.</li>
188 * </ul>
189 * @see None.
190 */
191extern VOID LOS_MemboxClr(VOID *pool, VOID *box);
192
193/**
194 * @ingroup los_membox
195 * @brief show membox info.
196 *
197 * @par Description:
198 * <ul>
199 * <li>This API is used to show the memory pool info.</li>
200 * </ul>
201 * @attention
202 * <ul>
203 * <li>The input pool parameter must be initialized via func LOS_MemboxInit.</li>
204 * </ul>
205 *
206 * @param pool [IN] Memory pool address.
207 *
208 * @retval VOID
209 * @par Dependency:
210 * <ul>
211 * <li>los_membox.h: the header file that contains the API declaration.</li>
212 * </ul>
213 * @see None.
214 */
215extern VOID LOS_ShowBox(VOID *pool);
216
217/**
218 * @ingroup los_membox
219 * @brief calculate membox information.
220 *
221 * @par Description:
222 * <ul>
223 * <li>This API is used to calculate membox information.</li>
224 * </ul>
225 * @attention
226 * <ul>
227 * <li>One parameter of this interface is a pointer, it should be a correct value, otherwise, the system may
228 * be abnormal.</li>
229 * </ul>
230 *
231 * @param boxMem [IN] Type #VOID* Pointer to the calculate membox.
232 * @param maxBlk [OUT] Type #UINT32* Record membox max block.
233 * @param blkCnt [OUT] Type #UINT32* Record membox block count alreay allocated.
234 * @param blkSize [OUT] Type #UINT32* Record membox block size.
235 *
236 * @retval #LOS_OK The heap status calculate success.
237 * @retval #LOS_NOK The membox status calculate with some error.
238 * @par Dependency:
239 * <ul><li>los_memory.h: the header file that contains the API declaration.</li></ul>
240 * @see LOS_MemAlloc | LOS_MemRealloc | LOS_MemFree
241 */
242extern UINT32 LOS_MemboxStatisticsGet(const VOID *boxMem, UINT32 *maxBlk, UINT32 *blkCnt, UINT32 *blkSize);
243
244#ifdef __cplusplus
245#if __cplusplus
246}
247#endif /* __cplusplus */
248#endif /* __cplusplus */
249
250#endif /* _LOS_MEMBOX_H */
VOID LOS_MemboxClr(VOID *pool, VOID *box)
Clear a memory block.
Definition: los_membox.c:201
VOID * LOS_MemboxAlloc(VOID *pool)
Request a memory block.
Definition: los_membox.c:150
struct tagMEMBOX_NODE LOS_MEMBOX_NODE
VOID LOS_ShowBox(VOID *pool)
show membox info.
Definition: los_membox.c:214
UINT32 LOS_MemboxFree(VOID *pool, VOID *box)
Free a memory block.
Definition: los_membox.c:174
UINT32 LOS_MemboxInit(VOID *pool, UINT32 poolSize, UINT32 blkSize)
Initialize a memory pool.
Definition: los_membox.c:106
UINT32 LOS_MemboxStatisticsGet(const VOID *boxMem, UINT32 *maxBlk, UINT32 *blkCnt, UINT32 *blkSize)
calculate membox information.
Definition: los_membox.c:241
LOS_MEMBOX_INFO OS_MEMBOX_S
Definition: los_membox.h:71
unsigned int UINT32
Definition: los_typedef.h:57
UINT32 uwBlkSize
Definition: los_membox.h:65
UINT32 uwBlkNum
Definition: los_membox.h:66
UINT32 uwBlkCnt
Definition: los_membox.h:67
LOS_MEMBOX_NODE stFreeList
Definition: los_membox.h:68
struct tagMEMBOX_NODE * pstNext
Definition: los_membox.h:57