1 /* ---------------------------------------------------------------------------- 2 * Copyright (c) Huawei Technologies Co., Ltd. 2013-2015. All rights reserved. 3 * Description: LiteOS memory Module Implementation 4 * Redistribution and use in source and binary forms, with or without modification, 5 * are permitted provided that the following conditions are met: 6 * 1. Redistributions of source code must retain the above copyright notice, this list of 7 * conditions and the following disclaimer. 8 * 2. Redistributions in binary form must reproduce the above copyright notice, this list 9 * of conditions and the following disclaimer in the documentation and/or other materials 10 * provided with the distribution. 11 * 3. Neither the name of the copyright holder nor the names of its contributors may be used 12 * to endorse or promote products derived from this software without specific prior written 13 * permission. 14 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS 15 * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, 16 * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 17 * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR 18 * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, 19 * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, 20 * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; 21 * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, 22 * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR 23 * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF 24 * ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 25 * --------------------------------------------------------------------------- */ 26 27 #ifndef _LOS_MEMBOX_H 28 #define _LOS_MEMBOX_H 29 30 #include "los_config.h" 31 #if (LOSCFG_PLATFORM_EXC == YES) 32 #include "los_memcheck.h" 33 #endif 34 35 #if (LOSCFG_MEMBOX == YES) 36 37 #define BOX_ALIGN_8 0x80000000 38 /* ---------------------------------------------------------------------------- 39 * Global Functions 40 * --------------------------------------------------------------------------- */ 41 /** 42 * @ingroup los_membox 43 * Define whether to check the address validity 44 */ 45 #if (LOSCFG_PLATFORM_EXC == YES) 46 #define LOS_MEMBOX_CHECK 47 extern UINT8 g_memMang[]; 48 #endif 49 50 typedef struct tagMemBoxCB { 51 UINT32 uwMaxBlk; 52 UINT32 uwBlkCnt; 53 UINT32 uwBlkSize; /* Memory block size */ 54 }OS_MEMBOX_S; 55 56 typedef OS_MEMBOX_S *OS_MEMBOX_S_P; 57 58 #ifdef LOS_MEMBOX_CHECK 59 #define LOS_MEMBOX_MAGIC_SIZE 4 60 #else 61 #define LOS_MEMBOX_MAGIC_SIZE 0 62 #endif 63 64 /** 65 * @ingroup los_membox 66 * @brief Initialize a memory pool. 67 * 68 * @par Description: 69 * <ul> 70 * <li>This API is used to initialize a memory pool.</li> 71 * </ul> 72 * @attention 73 * <ul> 74 * <li>The boxSize parameter value should match the following two conditions :</li> 75 * <li>1) Be less than or equal to the Memory pool size; 2) Be greater than the size of LOS_MEMBOX_INFO.</li> 76 * </ul> 77 * 78 * @param boxMem [IN] Memory pool address. 79 * @param boxSize [IN] Memory pool size. 80 * @param blkSize [IN] Memory block size. 81 * 82 * @retval #LOS_NOK The memory pool fails to be initialized. 83 * @retval #LOS_OK The memory pool is successfully initialized. 84 * @par Dependency: 85 * <ul> 86 * <li>los_membox.h: the header file that contains the API declaration.</li> 87 * </ul> 88 * @see None. 89 */ 90 extern UINT32 LOS_MemboxInit(VOID *boxMem, UINT32 boxSize, UINT32 blkSize); 91 92 /** 93 * @ingroup los_membox 94 * @brief Request a memory block. 95 * 96 * @par Description: 97 * <ul> 98 * <li>This API is used to request a memory block.</li> 99 * </ul> 100 * @attention 101 * <ul> 102 * <li>The input pool parameter must be initialized via func LOS_MemboxInit.</li> 103 * </ul> 104 * 105 * @param boxMem [IN] Memory pool address. 106 * 107 * @retval #VOID* The request is accepted, and return a memory block address. 108 * @retval #NULL The request fails. 109 * @par Dependency: 110 * <ul> 111 * <li>los_membox.h: the header file that contains the API declaration.</li> 112 * </ul> 113 * @see LOS_MemboxFree 114 */ 115 extern VOID *LOS_MemboxAlloc(VOID *boxMem); 116 117 /** 118 * @ingroup los_membox 119 * @brief Free a memory block. 120 * 121 * @par Description: 122 * <ul> 123 * <li>This API is used to free a memory block.</li> 124 * </ul> 125 * @attention 126 * <ul> 127 * <li>The input pool parameter must be initialized via func LOS_MemboxInit.</li> 128 * <li>The input pBox parameter must be allocated by LOS_MemboxAlloc.</li> 129 * </ul> 130 * 131 * @param boxMem [IN] Memory pool address. 132 * @param box [IN] Memory block address. 133 * 134 * @retval #LOS_NOK This memory block fails to be freed. 135 * @retval #LOS_OK This memory block is successfully freed. 136 * @par Dependency: 137 * <ul> 138 * <li>los_membox.h: the header file that contains the API declaration.</li> 139 * </ul> 140 * @see LOS_MemboxAlloc 141 */ 142 extern UINT32 LOS_MemboxFree(const VOID *boxMem, VOID *box); 143 144 /** 145 * @ingroup los_membox 146 * @brief Clear a memory block. 147 * 148 * @par Description: 149 * <ul> 150 * <li>This API is used to set the memory block value to be 0.</li> 151 * </ul> 152 * @attention 153 * <ul> 154 * <li>The input pool parameter must be initialized via func LOS_MemboxInit.</li> 155 * <li>The input pBox parameter must be allocated by LOS_MemboxAlloc.</li> 156 * </ul> 157 * 158 * @param boxMem [IN] Memory pool address. 159 * @param box [IN] Memory block address. 160 * 161 * @retval VOID 162 * @par Dependency: 163 * <ul> 164 * <li>los_membox.h: the header file that contains the API declaration.</li> 165 * </ul> 166 * @see None. 167 */ 168 extern VOID LOS_MemboxClr(const VOID *boxMem, VOID *box); 169 170 171 /** 172 * @ingroup los_membox 173 * @brief calculate membox information. 174 * 175 * @par Description: 176 * <ul> 177 * <li>This API is used to calculate membox information.</li> 178 * </ul> 179 * @attention 180 * <ul> 181 * <li>One parameter of this interface is a pointer, it should be a correct value, otherwise, the system may be 182 * abnormal.</li> 183 * </ul> 184 * 185 * @param boxMem [IN] Type #VOID* Pointer to the calculate membox. 186 * @param maxBlk [OUT] Type #UINT32* Record membox max block. 187 * @param blkCnt [OUT] Type #UINT32* Record membox block count alreay allocated. 188 * @param blkSize [OUT] Type #UINT32* Record membox block size. 189 * 190 * @retval #LOS_OK The heap status calculate success. 191 * @retval #LOS_NOK The membox status calculate with some error. 192 * @par Dependency: 193 * <ul><li>los_memory.h: the header file that contains the API declaration.</li></ul> 194 * @see LOS_MemAlloc | LOS_MemRealloc | LOS_MemFree 195 */ 196 extern UINT32 LOS_MemboxStatisticsGet(const VOID *boxMem, UINT32 *maxBlk, UINT32 *blkCnt, UINT32 *blkSize); 197 #endif 198 #endif 199