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 completion Completion 17 * @ingroup linux 18 */ 19 20 #ifndef _LINUX_COMPLETION_H 21 #define _LINUX_COMPLETION_H 22 23 #include "los_sys.h" 24 25 #ifdef __cplusplus 26 extern "C" { 27 #endif /* __cplusplus */ 28 29 enum CompletionState { 30 COMPLETION_ONE, 31 COMPLETION_ALL 32 }; 33 34 #define COMPLETION_EVT 0x1 35 36 typedef struct completion { 37 LOS_DL_LIST pendList; 38 UINT32 comCount; 39 enum CompletionState state; 40 } completion_t; 41 42 /** 43 * @ingroup completion 44 * @brief Initialize a completion. 45 * 46 * @par Description: 47 * This API is used to initialize a specified completion. 48 * @attention 49 * <ul> 50 * <li>The input parameter x must point to valid memory, otherwise, initilize a completion would failed.</li> 51 * </ul> 52 * 53 * @param x [IN] Pointer to the completion to be initialized, which must point to valid memory. 54 * 55 * @retval None. 56 * @par Dependency: none 57 * <ul><li>completion.h: the header file that contains the API declaration.</li></ul> 58 * @see None. 59 * @since Huawei LiteOS V100R001C00 60 */ 61 void init_completion(struct completion *x); 62 63 /** 64 * @ingroup completion 65 * @brief Wake up a task that is waiting on this completion. 66 * 67 * @par Description: 68 * This API is used to wake up a task that is waiting on the completion. 69 * @attention 70 * <ul> 71 * <li>The input parameter x must point to valid memory, otherwise, the system would be abnormal.</li> 72 * <li>It suggested that calling complete() after wait_for_completion() or wait_for_completion_timeout(), 73 * otherwise, wait_for_completion() or wait_for_completion_timeout() would not block 74 * because there is already a completion completed.</li> 75 * </ul> 76 * 77 * @param x [IN] Pointer to the completion on which the task to be woken up is waiting, 78 * which must point to valid memory. 79 * 80 * @retval None. 81 * @par Dependency: 82 * <ul> 83 * <li>this function should be used after init_completion() be called.</li> 84 * <li>completion.h: the header file that contains the API declaration.</li> 85 * </ul> 86 * @see None. 87 * @since Huawei LiteOS V100R001C00 88 */ 89 void complete(struct completion *x); 90 91 /** 92 * @ingroup completion 93 * @brief Wake up all tasks that are waiting on this completion. 94 * 95 * @par Description: 96 * This API is used to wake up all tasks that are waiting on the completion. 97 * @attention 98 * <ul> 99 * <li>The input parameter x must point to valid memory, otherwise, the system would be abnormal.</li> 100 * <li>It suggested that calling complete_all() after wait_for_completion() or wait_for_completion_timeout(), 101 * otherwise, wait_for_completion() or wait_for_completion_timeout() would not block 102 * because there is already a completion completed.</li> 103 * </ul> 104 * 105 * @param x [IN] Pointer to the completion on which the task to be woken up is waiting, 106 * which must point to valid memory. 107 * 108 * @retval None. 109 * @par Dependency: 110 * <ul> 111 * <li>this function should be used after init_completion() be called.</li> 112 * <li>completion.h: the header file that contains the API declaration.</li> 113 * </ul> 114 * @see None. 115 * @since Huawei LiteOS V100R001C00 116 */ 117 void complete_all(struct completion *x); 118 119 /** 120 * @ingroup completion 121 * @brief Wait on a completion within a certain time period. 122 * 123 * @par Description: 124 * This API is used to wait on a completion within a certain time period (timeout). 125 * @attention 126 * <ul> 127 * <li>The input parameter x must point to valid memory, otherwise, #timeout will be returned.</li> 128 * <li>Do not call this API in interrupt or system tasks, otherwise, #timeout will be returned.</li> 129 * <li>DO NOT call this API in software timer callback. </li> 130 * <li>The value range of parameter timeout is [0, 0xFFFFFFFF]</li> 131 * </ul> 132 * 133 * @param x [IN] Pointer to the completion to be waited on, which must point to valid memory. 134 * @param timeout [IN] Timeout interval for waiting on the completion (unit: Tick). 135 * 136 * @retval 0 The timeout period expires before the task is blocked or scheduled, or that timeout period is 0. 137 * @retval [1, 0xFFFFFFFF] Remaining waiting time. 138 * @par Dependency: 139 * <ul> 140 * <li>this function should be used after init_completion() be called.</li> 141 * <li>completion.h: the header file that contains the API declaration.</li> 142 * </ul> 143 * @see None. 144 * @since Huawei LiteOS V100R001C00 145 */ 146 unsigned long wait_for_completion_timeout(struct completion *x, unsigned long timeout); 147 148 /** 149 * @ingroup completion 150 * @brief Wait on a completion forever. 151 * 152 * @par Description: 153 * This API is used to wait on a completion forever. 154 * @attention 155 * <ul> 156 * <li>The input parameter x must point to valid memory, otherwise, the system would be abnormal.</li> 157 * <li>Can not be used in interrupt.</li> 158 * <li>DO NOT call this API in system tasks. </li> 159 * </ul> 160 * 161 * @param x [IN] Pointer to the completion to be waited on, which must point to valid memory. 162 * 163 * @retval None. 164 * @par Dependency: 165 * <ul> 166 * <li>this function should be used after init_completion() be called.</li> 167 * <li>completion.h: the header file that contains the API declaration.</li> 168 * </ul> 169 * @see None. 170 * @since Huawei LiteOS V100R001C00 171 */ 172 #define wait_for_completion(x) (void)wait_for_completion_timeout(x, LOS_WAIT_FOREVER) 173 174 #ifdef __cplusplus 175 } 176 #endif /* __cplusplus */ 177 178 #endif /* _LINUX_COMPLETION_H */ 179