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 * Description: OS Abstract Layer. 15 */ 16 17 /** 18 * @defgroup osal_completion osal_completion 19 */ 20 #ifndef __OSAL_COMPLETION_H__ 21 #define __OSAL_COMPLETION_H__ 22 23 #ifdef __cplusplus 24 #if __cplusplus 25 extern "C" { 26 #endif 27 #endif 28 29 typedef struct { 30 void *completion; 31 } osal_completion; 32 33 /** 34 * @ingroup osal_completion 35 * @brief Initialize a dynamically allocd completion. 36 * 37 * @param com [out] pointer to completion structure that is to be initialized 38 * 39 * @attention Must be freed with osal_complete_destory. 40 * 41 * @return OSAL_SUCCESS/OSAL_FAILURE 42 * 43 * @par Support System: 44 * linux liteos freertos. 45 */ 46 int osal_completion_init(osal_completion *com); 47 48 /** 49 * @ingroup osal_completion 50 * @brief signals a single thread waiting on this completion. 51 * 52 * @par Description: 53 * This will wake up a single thread waiting on this completion. 54 * Threads will be awakened in the same order in which they were queued. 55 * If this function wakes up a task, it executes a full memory barrier before accessing the task state. 56 * 57 * @param com [in] holds the state of this particular completion 58 * 59 * @par Support System: 60 * linux liteos freertos. 61 */ 62 void osal_complete(osal_completion *com); 63 64 /** 65 * @ingroup osal_completion 66 * @brief waits for completion of a task. 67 * 68 * @par Description: 69 * This waits to be signaled for completion of a specific task. 70 * It is NOT interruptible and there is no timeout. 71 * 72 * @param com [in] holds the state of this particular completion 73 * 74 * @par Support System: 75 * linux liteos freertos. 76 */ 77 void osal_wait_for_completion(osal_completion *com); 78 79 /** 80 * @ingroup osal_completion 81 * @brief waits for completion of a task (w/timeout) 82 * 83 * @par Description: 84 * This waits for either a completion of a specific task to be signaled or for a 85 * specified timeout to expire. The timeout is in jiffies. It is not interruptible. 86 * 87 * @param com [in] holds the state of this particular completion 88 * @param timeout [in] jeffies in linux, tick in liteos 89 * 90 * @return return 0 if timed out, and positive (left time till timeout) if completed, or -1 if failed. 91 * 92 * @par Support System: 93 * linux liteos 94 */ 95 unsigned long osal_wait_for_completion_timeout(osal_completion *com, unsigned long timeout); 96 97 /** 98 * @ingroup osal_completion 99 * @brief signals all threads waiting on this completion. 100 * 101 * @par Description: 102 * This will wake up all threads waiting on this particular completion event. 103 * If this function wakes up a task, it executes a full memory barrier before accessing the task state. 104 * 105 * @param com [in] holds the state of this particular completion 106 * 107 * @par Support System: 108 * linux liteos. 109 */ 110 void osal_complete_all(osal_completion *com); 111 112 /** 113 * @ingroup osal_completion 114 * @brief free a dynamically allocd completion. 115 * 116 * @par Description: 117 * free a dynamically allocd completion. 118 * 119 * @param com [in] holds the state of this particular completion 120 * 121 * @attention this API may free memory, com Must be from osal_complete_init 122 * @par Support System: 123 * linux liteos freertos. 124 */ 125 void osal_complete_destory(osal_completion *com); 126 127 #ifdef __cplusplus 128 #if __cplusplus 129 } 130 #endif 131 #endif 132 #endif /* __OSAL_COMPLETION_H__ */