1 /*- 2 * Copyright (c) 2010 Isilon Systems, Inc. 3 * Copyright (c) 2010 iX Systems, Inc. 4 * Copyright (c) 2010 Panasas, Inc. 5 * Copyright (c) 2013, 2014 Mellanox Technologies, Ltd. 6 * All rights reserved. 7 * 8 * Redistribution and use in source and binary forms, with or without 9 * modification, are permitted provided that the following conditions 10 * are met: 11 * 1. Redistributions of source code must retain the above copyright 12 * notice unmodified, this list of conditions, and the following 13 * disclaimer. 14 * 2. Redistributions in binary form must reproduce the above copyright 15 * notice, this list of conditions and the following disclaimer in the 16 * documentation and/or other materials provided with the distribution. 17 * 18 * THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR 19 * IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES 20 * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. 21 * IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, 22 * INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT 23 * NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, 24 * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY 25 * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 26 * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF 27 * THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 28 * 29 * $FreeBSD: releng/12.2/sys/compat/linuxkpi/common/include/linux/completion.h 334427 2018-05-31 12:55:38Z hselasky $ 30 */ 31 #ifndef _LINUX_COMPLETION_H_ 32 #define _LINUX_COMPLETION_H_ 33 34 #include "los_sys.h" 35 36 #ifdef __cplusplus 37 #if __cplusplus 38 extern "C" { 39 #endif /* __cplusplus */ 40 #endif /* __cplusplus */ 41 42 enum CompletionState { 43 COMPLETION_ONE, 44 COMPLETION_ALL 45 }; 46 47 #define COMPLETION_EVT 0x1 48 49 typedef struct completion { 50 LOS_DL_LIST comList; 51 UINT32 comCount; 52 enum CompletionState state; 53 } completion_t; 54 55 #define init_completion(x) \ 56 linux_init_completion(x) 57 58 /* This inline function should be used to reinitialize a completion structure so it can 59 * be reused. This is especially important after complete_all() is used. 60 */ 61 #define reinit_completion(x) \ 62 do { (x)->comCount = 0; } while (0) 63 64 #define complete(x) \ 65 linux_complete(x) 66 67 #define wait_for_completion(x) \ 68 linux_wait_for_completion(x) 69 70 #define wait_for_completion_timeout(x, timeout) \ 71 linux_wait_for_completion_timeout(x, timeout) 72 73 #define complete_all(x) \ 74 linux_complete_all(x) 75 76 #define completion_done(x) \ 77 linux_completion_done(x) 78 79 /** 80 * @ingroup completion 81 * @brief Initialize a completion. 82 * 83 * @par Description: 84 * This API is used to initialize a specified completion. 85 * @attention 86 * <ul> 87 * <li>The input parameter x must point to valid memory, otherwise, initilize a completion would failed.</li> 88 * </ul> 89 * 90 * @param x [IN] Pointer to the completion to be initialized,which must point to valid memory. 91 * 92 * @retval None. 93 * @par Dependency: none 94 * <ul><li>completion.h: the header file that contains the API declaration.</li></ul> 95 * @see 96 */ 97 extern void linux_init_completion(struct completion *x); 98 99 /** 100 * @ingroup completion 101 * @brief Wake up a task that is waiting on this completion. 102 * 103 * @par Description: 104 * This API is used to wake up a task that is waiting on the completion. 105 * @attention 106 * <ul> 107 * <li>The input parameter x must point to valid memory, otherwise, the system would be abnormal.</li> 108 * <li>It suggested that calling complete() after wait_for_completion() or wait_for_completion_timeout(), 109 * otherwise, wait_for_completion() or wait_for_completion_timeout() would not block 110 * because there is already a completion completed.</li> 111 * </ul> 112 * 113 * @param x [IN] Pointer to the completion on which the task to be woken up is waiting, 114 * which must point to valid memory. 115 * 116 * @retval None. 117 * @par Dependency: 118 * <ul> 119 * <li>this function should be used after init_completion() be called.</li> 120 * <li>completion.h: the header file that contains the API declaration.</li> 121 * </ul> 122 * @see 123 */ 124 extern void linux_complete(struct completion *x); 125 126 /** 127 * @ingroup completion 128 * @brief Wait on a completion forever. 129 * 130 * @par Description: 131 * This API is used to wait on a completion forever. 132 * @attention 133 * <ul> 134 * <li>The input parameter x must point to valid memory, otherwise, the system would be abnormal.</li> 135 * <li>Can not be used in interrupt.</li> 136 * <li>DO NOT call this API in system tasks. </li> 137 * </ul> 138 * 139 * @param x [IN] Pointer to the completion to be waited on, which must point to valid memory. 140 * 141 * @retval None. 142 * @par Dependency: 143 * <ul> 144 * <li>this function should be used after init_completion() be called.</li> 145 * <li>completion.h: the header file that contains the API declaration.</li> 146 * </ul> 147 * @see 148 */ 149 extern void linux_wait_for_completion(struct completion *x); 150 151 /** 152 * @ingroup completion 153 * @brief Wait on a completion within a certain time period. 154 * 155 * @par Description: 156 * This API is used to wait on a completion within a certain time period (timeout). 157 * @attention 158 * <ul> 159 * <li>The input parameter x must point to valid memory, otherwise, the system would be abnormal.</li> 160 * <li>Timeout interval timeout should be in [1 , 0xFFFFFFFF], otherwise, 161 * it would return OS_WAIT_COMPLETION_ERROR but not wait for completion.</li> 162 * <li>Can not be used in interrupt.</li> 163 * <li>DO NOT call this API in software timer callback. </li> 164 * </ul> 165 * 166 * @param x [IN] Pointer to the completion to be waited on, which must point to valid memory. 167 * @param timeout [IN] Timeout interval for waiting on the completion (unit: Tick). 168 * 169 * @retval 0 The timeout period expires before the task is blocked or scheduled, or that timeout period is 0. 170 * @retval [1,0xFFFFFFFF] Remaining waiting time. 171 * @par Dependency: 172 * <ul> 173 * <li>this function should be used after init_completion() be called.</li> 174 * <li>completion.h: the header file that contains the API declaration.</li> 175 * </ul> 176 * @see 177 */ 178 extern unsigned long linux_wait_for_completion_timeout(struct completion *x, unsigned long timeout); 179 180 /** 181 * @ingroup completion 182 * @brief Wake up all tasks that are waiting on this completion. 183 * 184 * @par Description: 185 * This API is used to wake up all tasks that are waiting on the completion. 186 * @attention 187 * <ul> 188 * <li>The input parameter x must point to valid memory, otherwise, the system would be abnormal.</li> 189 * <li>It suggested that calling complete_all() after wait_for_completion() or wait_for_completion_timeout(), 190 * otherwise, wait_for_completion() or wait_for_completion_timeout() would not block 191 * because there is already a completion completed.</li> 192 * </ul> 193 * 194 * @param x [IN] Pointer to the completion on which the task to be woken up is waiting, 195 * which must point to valid memory. 196 * 197 * @retval None. 198 * @par Dependency: 199 * <ul> 200 * <li>this function should be used after init_completion() be called.</li> 201 * <li>completion.h: the header file that contains the API declaration.</li> 202 * </ul> 203 * @see 204 */ 205 extern void linux_complete_all(struct completion *x); 206 extern int linux_completion_done(struct completion *x); 207 208 #ifdef __cplusplus 209 #if __cplusplus 210 } 211 #endif /* __cplusplus */ 212 #endif /* __cplusplus */ 213 214 #endif /* _LINUX_COMPLETION_H_ */ 215