1 /* 2 * Copyright (c) 2020 HiSilicon (Shanghai) Technologies CO., LIMITED. 3 * Licensed under the Apache License, Version 2.0 (the "License"); 4 * you may not use this file except in compliance with the License. 5 * You may obtain a copy of the License at 6 * 7 * http://www.apache.org/licenses/LICENSE-2.0 8 * 9 * Unless required by applicable law or agreed to in writing, software 10 * distributed under the License is distributed on an "AS IS" BASIS, 11 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 * See the License for the specific language governing permissions and 13 * limitations under the License. 14 */ 15 /** 16 * @defgroup rwsem Read write semaphore 17 * @ingroup linux 18 */ 19 20 #ifndef _LINUX_RWSEM_H 21 #define _LINUX_RWSEM_H 22 23 #include "los_list.h" 24 25 #ifdef __cplusplus 26 extern "C" { 27 #endif /* __cplusplus */ 28 29 #define RWSEM_UNINIT_VALUE 0xFFFFFFFF 30 31 /** 32 * @ingroup rwsem 33 * rw semaphore structure. 34 */ 35 struct rw_semaphore { 36 UINT32 rwsemHandle; 37 }; 38 39 extern void InitRwsem(struct rw_semaphore *rwsem); 40 41 /** 42 * @ingroup rwsem 43 * @brief Statically defines and initializes a read/write semaphore. 44 * 45 * @par Description: 46 * This API is used to statically define and initialize a read/write semaphore. 47 * 48 * @attention 49 * None. 50 * 51 * @param semName [IN] the name of the read/write semaphore to be defined. 52 * 53 * @retval #None 54 * @par Dependency: 55 * <ul> 56 * <li>rwsem.h: the header file that contains the API declaration.</li> 57 * </ul> 58 * @see None. 59 */ 60 #define DECLARE_RWSEM(semName) \ 61 struct rw_semaphore (semName) = {RWSEM_UNINIT_VALUE} 62 63 /** 64 * @ingroup rwsem 65 * @brief Dynamically initializes a read/write semaphore. 66 * 67 * @par Description: 68 * This API is used to dynamically initialize a read/write semaphore. 69 * 70 * @attention 71 * None. 72 * 73 * @param rwsem [IN] the semaphore to be initialized. 74 * 75 * @retval #None 76 * @par Dependency: 77 * <ul> 78 * <li>rwsem.h: the header file that contains the API declaration.</li> 79 * </ul> 80 * @see None. 81 */ 82 #define init_rwsem(rwsem) InitRwsem(rwsem) 83 84 /** 85 * @ingroup rwsem 86 * @brief acquire the semaphore for reading. 87 * 88 * @par Description: 89 * This API is used to acquire the semaphore for reading. If no more tasks are allowed to acquire the semaphore, 90 * calling this function will put the task to sleep until the semaphore is released. 91 * 92 * @attention 93 * <ul> 94 * <li>Blocking interface, disallowed in interrupt isr handler. </li> 95 * </ul> 96 * 97 * @param rwsem [IN] the semaphore to be acquired. 98 * 99 * @retval #None 100 * @par Dependency: 101 * <ul> 102 * <li>rwsem.h: the header file that contains the API declaration.</li> 103 * </ul> 104 * @see None. 105 */ 106 void down_read(struct rw_semaphore *rwsem); 107 108 /** 109 * @ingroup rwsem 110 * @brief try to acquire the semaphore for reading, without waiting. 111 * 112 * @par Description: 113 * This API is used to try to acquire the semaphore for reading, without waiting. 114 * 115 * @attention 116 * <ul> 117 * <li> The return value is inconsistent with the Linux standard interface definition. </li> 118 * </ul> 119 * 120 * @param rwsem [IN] the semaphore to be acquired. 121 * 122 * @retval # 1 the semaphore has been acquired successfully. 123 * @retval # 0 it cannot be acquired. 124 * @par Dependency: 125 * <ul> 126 * <li>rwsem.h: the header file that contains the API declaration.</li> 127 * </ul> 128 * @see None. 129 */ 130 int down_read_trylock(struct rw_semaphore *rwsem); 131 132 /** 133 * @ingroup rwsem 134 * @brief acquire the semaphore for writing. 135 * 136 * @par Description: 137 * This API is used to acquire the semaphore for writing. If no more tasks are allowed to acquire the semaphore, 138 * calling this function will put the task to sleep until the semaphore is released. 139 * 140 * @attention 141 * <ul> 142 * <li>Blocking interface, disallowed in interrupt isr handler. </li> 143 * </ul> 144 * 145 * @param rwsem [IN] the semaphore to be acquired. 146 * 147 * @retval #None 148 * @par Dependency: 149 * <ul> 150 * <li>rwsem.h: the header file that contains the API declaration.</li> 151 * </ul> 152 * @see None. 153 */ 154 void down_write(struct rw_semaphore *rwsem); 155 156 /** 157 * @ingroup rwsem 158 * @brief try to acquire the semaphore for writing, without waiting. 159 * 160 * @par Description: 161 * This API is used to try to acquire the semaphore for writing, without waiting. 162 * 163 * @attention 164 * <ul> 165 * <li> The return value is inconsistent with the Linux standard interface definition. </li> 166 * </ul> 167 * 168 * @param rwsem [IN] the semaphore to be acquired. 169 * 170 * @retval # 1 the semaphore has been acquired successfully. 171 * @retval # 0 it cannot be acquired. 172 * @par Dependency: 173 * <ul> 174 * <li>rwsem.h: the header file that contains the API declaration.</li> 175 * </ul> 176 * @see None. 177 */ 178 int down_write_trylock(struct rw_semaphore *rwsem); 179 180 /** 181 * @ingroup rwsem 182 * @brief release the read semaphore. 183 * 184 * @par Description: 185 * This API is used to release the read semaphore. 186 * 187 * @attention 188 * None. 189 * 190 * @param rwsem [IN] the semaphore to be acquired. 191 * 192 * @retval # None. 193 * @par Dependency: 194 * <ul> 195 * <li>rwsem.h: the header file that contains the API declaration.</li> 196 * </ul> 197 * @see None. 198 */ 199 void up_read(struct rw_semaphore *rwsem); 200 201 /** 202 * @ingroup rwsem 203 * @brief release the write semaphore. 204 * 205 * @par Description: 206 * This API is used to release the write semaphore. 207 * 208 * @attention 209 * None. 210 * 211 * @param rwsem [IN] the semaphore to be acquired. 212 * 213 * @retval # None. 214 * @par Dependency: 215 * <ul> 216 * <li>rwsem.h: the header file that contains the API declaration.</li> 217 * </ul> 218 * @see None. 219 */ 220 void up_write(struct rw_semaphore *rwsem); 221 222 /** 223 * @ingroup rwsem 224 * @brief Downgrades the write semaphore to the read semaphore. 225 * 226 * @par Description: 227 * This API is used to downgrade the write semaphore to the read semaphore. 228 * 229 * @attention 230 * None. 231 * 232 * @param rwsem [IN] the semaphore to be acquired. 233 * 234 * @retval # None. 235 * @par Dependency: 236 * <ul> 237 * <li>rwsem.h: the header file that contains the API declaration.</li> 238 * </ul> 239 * @see None. 240 */ 241 void downgrade_write(struct rw_semaphore *rwsem); 242 243 /** 244 * @ingroup rwsem 245 * @brief destroy the semaphore at the address pointed to by rwsem. 246 * 247 * @par Description: 248 * This API is used to destroy the read and write semaphore. 249 * 250 * @attention 251 * None. 252 * 253 * @param rwsem [IN] the semaphore to be acquired. 254 * 255 * @retval # 1 the semaphore has been destoryed successfully. 256 * @retval # 0 it cannot be destoryed. 257 * @par Dependency: 258 * <ul> 259 * <li>rwsem.h: the header file that contains the API declaration.</li> 260 * </ul> 261 * @see None. 262 */ 263 int rwsem_destory(struct rw_semaphore *rwsem); 264 265 #ifdef __cplusplus 266 } 267 #endif /* __cplusplus */ 268 269 #endif /* _LINUX_RWSEM_H */ 270