1 /* 2 * Copyright (c) 2020-2023 Huawei Device Co., Ltd. 3 * 4 * HDF is dual licensed: you can use it either under the terms of 5 * the GPL, or the BSD license, at your option. 6 * See the LICENSE file in the root of this repository for complete details. 7 */ 8 9 /** 10 * @addtogroup OSAL 11 * @{ 12 * 13 * @brief Defines the structures and interfaces for the Operating System Abstraction Layer (OSAL) module. 14 * 15 * The OSAL module OpenHarmony OS interface differences and provides unified OS interfaces externally, 16 * including the memory management, thread, mutex, spinlock, semaphore, timer, file, interrupt, time, 17 * atomic, firmware, and I/O operation modules. 18 * 19 * @since 1.0 20 * @version 1.0 21 */ 22 23 /** 24 * @file osal_thread.h 25 * 26 * @brief Declares thread types and interfaces. 27 * 28 * Threads created by the OSAL module are in the detached state. When releasing threads, the service module must 29 * first terminate its own threads and then {@link OsalThreadDestroy} can be called to release applied resources. 30 * 31 * @since 1.0 32 * @version 1.0 33 */ 34 #ifndef OSAL_THREAD_H 35 #define OSAL_THREAD_H 36 37 #include "hdf_base.h" 38 39 #ifdef __cplusplus 40 extern "C" { 41 #endif /* __cplusplus */ 42 43 /** 44 * @brief Enumerates thread priorities. 45 * 46 * @since 1.0 47 * @version 1.0 48 */ 49 typedef enum { 50 OSAL_THREAD_PRI_LOW, /**< Low priority */ 51 OSAL_THREAD_PRI_DEFAULT, /**< Default priority */ 52 OSAL_THREAD_PRI_HIGH, /**< High priority */ 53 OSAL_THREAD_PRI_HIGHEST /**< Highest priority */ 54 } OSAL_THREAD_PRIORITY; 55 56 /** 57 * @brief Describes thread parameters. 58 * 59 * @since 1.0 60 * @version 1.0 61 */ 62 struct OsalThreadParam { 63 char *name; /**< Thread name */ 64 size_t stackSize; /**< Thread stack size, which may cause thread stack overflow if it is too small */ 65 OSAL_THREAD_PRIORITY priority; /**< Thread priority */ 66 int policy; /**< Thread scheduling policy */ 67 }; 68 69 /** 70 * @brief Defines a thread callback function type. 71 * 72 * @since 1.0 73 * @version 1.0 74 */ 75 typedef int (*OsalThreadEntry)(void *); 76 77 /** 78 * @brief Describes a thread. 79 * 80 * @since 1.0 81 * @version 1.0 82 */ 83 struct OsalThread { 84 void *realThread; /**< Pointer to a created thread object */ 85 }; 86 87 /** 88 * @brief Defines a thread macro. 89 * 90 * @since 1.0 91 * @version 1.0 92 */ 93 #define OSAL_DECLARE_THREAD(thread) struct OsalThread thread 94 95 /** 96 * @brief Creates a thread. 97 * 98 * @param thread Indicates the pointer to the thread {@link OsalThread}. 99 * @param threadEntry Indicates the thread callback function {@link OsalThreadEntry}. 100 * @param entryPara Indicates the pointer to the parameter passed to the thread callback function. 101 * 102 * @return Returns a value listed below: \n 103 * HDF_STATUS | Description 104 * ----------------------| ----------------------- 105 * HDF_SUCCESS | The operation is successful. 106 * HDF_ERR_INVALID_PARAM | Invalid parameter. 107 * HDF_ERR_MALLOC_FAIL | Memory allocation fails. 108 * 109 * @since 1.0 110 * @version 1.0 111 */ 112 int32_t OsalThreadCreate(struct OsalThread *thread, OsalThreadEntry threadEntry, void *entryPara); 113 114 /** 115 * @brief Binds a thread to a specified CPU. 116 * 117 * Call this function before {@link OsalThreadStart} and after {@link OsalThreadCreate} 118 * if you need to run a created thread on a specified CPU. 119 * 120 * @param thread Indicates the pointer to the thread {@link OsalThread}. 121 * @param cpuID Indicates the ID of the specified CPU. 122 * 123 * @return Returns a value listed below: \n 124 * HDF_STATUS | Description 125 * ----------------------| ----------------------- 126 * HDF_SUCCESS | The operation is successful. 127 * HDF_ERR_INVALID_PARAM | Invalid parameter. 128 * 129 * @since 1.0 130 * @version 1.0 131 */ 132 int32_t OsalThreadBind(struct OsalThread *thread, unsigned int cpuID); 133 134 /** 135 * @brief Starts a thread. 136 * 137 * @param thread Indicates the pointer to the thread {@link OsalThread}. 138 * @param param Indicates the pointer to the parameter used to start a thread. For details, see {@link OsalThreadParam}. 139 * 140 * @return Returns a value listed below: \n 141 * HDF_STATUS | Description 142 * ----------------------| ----------------------- 143 * HDF_SUCCESS | The operation is successful. 144 * HDF_FAILURE | Failed to invoke the system function to start the thread. 145 * HDF_ERR_INVALID_PARAM | Invalid parameter. 146 * 147 * @since 1.0 148 * @version 1.0 149 */ 150 int32_t OsalThreadStart(struct OsalThread *thread, const struct OsalThreadParam *param); 151 152 /** 153 * @brief Destroys a thread. 154 * 155 * @param thread Indicates the pointer to the thread {@link OsalThread}. 156 * @return Returns a value listed below: \n 157 * HDF_STATUS | Description 158 * ----------------------| ----------------------- 159 * HDF_SUCCESS | The operation is successful. 160 * HDF_FAILURE | Failed to invoke the system function to destroy the thread. 161 * HDF_ERR_INVALID_PARAM | Invalid parameter. 162 * 163 * @since 1.0 164 * @version 1.0 165 */ 166 int32_t OsalThreadDestroy(struct OsalThread *thread); 167 168 /** 169 * @brief Suspends a thread. 170 * 171 * @param thread Indicates the pointer to the thread {@link OsalThread}. 172 * @return Returns a value listed below: \n 173 * HDF_STATUS | Description 174 * ----------------------| ----------------------- 175 * HDF_SUCCESS | The operation is successful. 176 * HDF_FAILURE | Failed to invoke the system function to suspend the thread. 177 * HDF_ERR_INVALID_PARAM | Invalid parameter. 178 * 179 * @since 1.0 180 * @version 1.0 181 */ 182 int32_t OsalThreadSuspend(struct OsalThread *thread); 183 184 /** 185 * @brief Resumes a thread. 186 * 187 * @param thread Indicates the pointer to the thread {@link OsalThread}. 188 * @return Returns a value listed below: \n 189 * HDF_STATUS | Description 190 * ----------------------| ----------------------- 191 * HDF_SUCCESS | The operation is successful. 192 * HDF_FAILURE | Failed to invoke the system function to resume the thread. 193 * HDF_ERR_INVALID_PARAM | Invalid parameter. 194 * 195 * @since 1.0 196 * @version 1.0 197 */ 198 int32_t OsalThreadResume(struct OsalThread *thread); 199 200 #ifdef __cplusplus 201 } 202 #endif /* __cplusplus */ 203 204 #endif /* OSAL_THREAD_H */ 205 /** @} */ 206