1 /* 2 * Copyright (c) 2020-2021 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 }; 67 68 /** 69 * @brief Defines a thread callback function type. 70 * 71 * @since 1.0 72 * @version 1.0 73 */ 74 typedef int (*OsalThreadEntry)(void *); 75 76 /** 77 * @brief Describes a thread. 78 * 79 * @since 1.0 80 * @version 1.0 81 */ 82 struct OsalThread { 83 void *realThread; /**< Pointer to a created thread object */ 84 }; 85 86 /** 87 * @brief Defines a thread macro. 88 * 89 * @since 1.0 90 * @version 1.0 91 */ 92 #define OSAL_DECLARE_THREAD(thread) struct OsalThread thread 93 94 /** 95 * @brief Creates a thread. 96 * 97 * @param thread Indicates the pointer to the thread {@link OsalThread}. 98 * @param threadEntry Indicates the thread callback function {@link OsalThreadEntry}. 99 * @param entryPara Indicates the pointer to the parameter passed to the thread callback function. 100 * 101 * @return Returns a value listed below: \n 102 * HDF_STATUS | Description 103 * ----------------------| ----------------------- 104 * HDF_SUCCESS | The operation is successful. 105 * HDF_ERR_INVALID_PARAM | Invalid parameter. 106 * HDF_ERR_MALLOC_FAIL | Memory allocation fails. 107 * 108 * @since 1.0 109 * @version 1.0 110 */ 111 int32_t OsalThreadCreate(struct OsalThread *thread, OsalThreadEntry threadEntry, void *entryPara); 112 113 /** 114 * @brief Binds a thread to a specified CPU. 115 * 116 * Call this function before {@link OsalThreadStart} and after {@link OsalThreadCreate} 117 * if you need to run a created thread on a specified CPU. 118 * 119 * @param thread Indicates the pointer to the thread {@link OsalThread}. 120 * @param cpuID Indicates the ID of the specified CPU. 121 * 122 * @return Returns a value listed below: \n 123 * HDF_STATUS | Description 124 * ----------------------| ----------------------- 125 * HDF_SUCCESS | The operation is successful. 126 * HDF_ERR_INVALID_PARAM | Invalid parameter. 127 * 128 * @since 1.0 129 * @version 1.0 130 */ 131 int32_t OsalThreadBind(struct OsalThread *thread, unsigned int cpuID); 132 133 /** 134 * @brief Starts a thread. 135 * 136 * @param thread Indicates the pointer to the thread {@link OsalThread}. 137 * @param param Indicates the pointer to the parameter used to start a thread. For details, see {@link OsalThreadParam}. 138 * 139 * @return Returns a value listed below: \n 140 * HDF_STATUS | Description 141 * ----------------------| ----------------------- 142 * HDF_SUCCESS | The operation is successful. 143 * HDF_FAILURE | Failed to invoke the system function to start the thread. 144 * HDF_ERR_INVALID_PARAM | Invalid parameter. 145 * 146 * @since 1.0 147 * @version 1.0 148 */ 149 int32_t OsalThreadStart(struct OsalThread *thread, const struct OsalThreadParam *param); 150 151 /** 152 * @brief Destroys a thread. 153 * 154 * @param thread Indicates the pointer to the thread {@link OsalThread}. 155 * @return Returns a value listed below: \n 156 * HDF_STATUS | Description 157 * ----------------------| ----------------------- 158 * HDF_SUCCESS | The operation is successful. 159 * HDF_FAILURE | Failed to invoke the system function to destroy the thread. 160 * HDF_ERR_INVALID_PARAM | Invalid parameter. 161 * 162 * @since 1.0 163 * @version 1.0 164 */ 165 int32_t OsalThreadDestroy(struct OsalThread *thread); 166 167 /** 168 * @brief Suspends a thread. 169 * 170 * @param thread Indicates the pointer to the thread {@link OsalThread}. 171 * @return Returns a value listed below: \n 172 * HDF_STATUS | Description 173 * ----------------------| ----------------------- 174 * HDF_SUCCESS | The operation is successful. 175 * HDF_FAILURE | Failed to invoke the system function to suspend the thread. 176 * HDF_ERR_INVALID_PARAM | Invalid parameter. 177 * 178 * @since 1.0 179 * @version 1.0 180 */ 181 int32_t OsalThreadSuspend(struct OsalThread *thread); 182 183 /** 184 * @brief Resumes a thread. 185 * 186 * @param thread Indicates the pointer to the thread {@link OsalThread}. 187 * @return Returns a value listed below: \n 188 * HDF_STATUS | Description 189 * ----------------------| ----------------------- 190 * HDF_SUCCESS | The operation is successful. 191 * HDF_FAILURE | Failed to invoke the system function to resume the thread. 192 * HDF_ERR_INVALID_PARAM | Invalid parameter. 193 * 194 * @since 1.0 195 * @version 1.0 196 */ 197 int32_t OsalThreadResume(struct OsalThread *thread); 198 199 #ifdef __cplusplus 200 } 201 #endif /* __cplusplus */ 202 203 #endif /* OSAL_THREAD_H */ 204 /** @} */ 205