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_task osal_task 19 */ 20 #ifndef __OSAL_TASK_H__ 21 #define __OSAL_TASK_H__ 22 23 #ifdef __cplusplus 24 #if __cplusplus 25 extern "C" { 26 #endif 27 #endif 28 29 #if defined(__LITEOS__) || defined(__FREERTOS__) 30 #define OSAL_TASK_PRIORITY_ABOVE_HIGH 2 31 #define OSAL_TASK_PRIORITY_HIGH 3 32 #define OSAL_TASK_PRIORITY_BELOW_HIGH 4 33 #define OSAL_TASK_PRIORITY_ABOVE_MIDDLE 5 34 #define OSAL_TASK_PRIORITY_MIDDLE 6 35 #define OSAL_TASK_PRIORITY_BELOW_MIDDLE 7 36 #define OSAL_TASK_PRIORITY_ABOVE_LOW 8 37 #define OSAL_TASK_PRIORITY_LOW 10 38 #define OSAL_TASK_PRIORITY_BELOW_LOW 11 39 #elif defined(__KERNEL__) 40 #define OSAL_TASK_PRIORITY_ABOVE_HIGH 99 41 #define OSAL_TASK_PRIORITY_HIGH 90 42 #define OSAL_TASK_PRIORITY_BELOW_HIGH 80 43 #define OSAL_TASK_PRIORITY_ABOVE_MIDDLE 70 44 #define OSAL_TASK_PRIORITY_MIDDLE 60 45 #define OSAL_TASK_PRIORITY_BELOW_MIDDLE 50 46 #define OSAL_TASK_PRIORITY_ABOVE_LOW 40 47 #define OSAL_TASK_PRIORITY_LOW 30 48 #define OSAL_TASK_PRIORITY_BELOW_LOW 20 49 #else 50 #define OSAL_TASK_PRIORITY_ABOVE_HIGH 2 51 #define OSAL_TASK_PRIORITY_HIGH 3 52 #define OSAL_TASK_PRIORITY_BELOW_HIGH 4 53 #define OSAL_TASK_PRIORITY_ABOVE_MIDDLE 5 54 #define OSAL_TASK_PRIORITY_MIDDLE 6 55 #define OSAL_TASK_PRIORITY_BELOW_MIDDLE 7 56 #define OSAL_TASK_PRIORITY_ABOVE_LOW 8 57 #define OSAL_TASK_PRIORITY_LOW 10 58 #define OSAL_TASK_PRIORITY_BELOW_LOW 11 59 #endif 60 typedef struct { 61 void *task; 62 } osal_task; 63 typedef int (*osal_kthread_handler)(void *data); 64 65 /** 66 * @ingroup osal_task 67 * 68 * @brief Provides an interface for creating a thread and invokes kthread_run for creating a kernel thread. 69 * 70 * @par Description: 71 * Provides an interface for creating a thread and invokes kthread_run for creating a kernel thread. 72 * If the size of the task stack to be created is less than or equal to MINIMAL_STACK_SIZE, 73 * set stack_size to MINIMAL_STACK_SIZE to specify the default size of the task stack. 74 * The stack size is determined by whether it is big enough to avoid task stack overflow. 75 * 76 * @param stack_size [in] Size of the stack space of the thread. 77 * @param handler [in] Functions to be processed by the thread 78 * @param data [in] Function handler data. 79 * @param name [in] Thread name displayed. 80 * 81 * @retval osal_task* If the thread is successfully created, the pointer of the thread is returned. 82 * @retval NULL If the thread fails to be created, NULL is returned. 83 * 84 * @par Support System: 85 * linux liteos freertos. 86 */ 87 osal_task *osal_kthread_create(osal_kthread_handler handler, void *data, const char *name, unsigned int stack_size); 88 89 /** 90 * @ingroup osal_task 91 * 92 * @brief Setting the priority of a thread. 93 * 94 * @par Description: 95 * Sets the priority of the current thread. 96 * 97 * @param task [in] Threads to be prioritized. 98 * @param priority [in] Priority to be set, It must be one of the following three priorities. 99 * OSAL_TASK_PRIORITY_HIGH, OSAL_TASK_PRIORITY_MIDDLE, OSAL_TASK_PRIORITY_LOW. 100 * 101 * @return OSAL_FAILURE/OSAL_SUCCESS. 102 * 103 * @par Support System: 104 * linux liteos freertos. 105 */ 106 int osal_kthread_set_priority(osal_task *task, unsigned int priority); 107 108 /** 109 * @ingroup osal_task 110 * 111 * @brief Setting the CPU Affinity of a Task. 112 * 113 * @par Description: 114 * Setting the CPU Affinity of a Task. 115 * 116 * @param task [in] Thread to change 117 * @param cpu_mask [in] Specifies the mask of the CPU.You can only choose one of the following 118 * OSAL_CPU_ALL, OSAL_CPU_0, OSAL_CPU_1, OSAL_CPU_2, OSAL_CPU_3. 119 * 120 * @par Support System: 121 * linux liteos . 122 */ 123 void osal_kthread_set_affinity(osal_task *task, int cpu_mask); 124 125 /** 126 * @ingroup osal_task 127 * @brief Check whether the thread is running. 128 * 129 * @par Description: 130 * A function used to determine whether a thread in the kernel is still running. 131 * 132 * @retval 0 If one of the current threads continues to run in the kernel. 133 * @retval 1 If a current thread is stopped somewhere in the kernel by using kthread_stop(struct task_struct *). 134 * 135 * @par Support System: 136 * linux liteos. 137 */ 138 int osal_kthread_should_stop(void); 139 140 /** 141 * @ingroup osal_task 142 * 143 * @brief This function is used to wake up a thread. 144 * 145 * @par Description: 146 * This function is used to wake up a thread. 147 * 148 * @param task [in] Thread you want to wake up. 149 * 150 * @retval 0 If the wakeup is successful, 0 is returned. 151 * @retval -1 If the wakeup fails, -1 is returned. 152 * 153 * @par Support System: 154 * linux. 155 */ 156 int osal_kthread_wakeup_process(osal_task *task); 157 158 /** 159 * @ingroup osal_task 160 * 161 * @brief Bind the created thread to run on the execution CPU core. 162 * 163 * @par Description: 164 * Bind the created thread to run on the execution CPU core. 165 * 166 * @param task [in] Thread you want to bind. 167 * @param cpu [in] This kernel thread is bound to the CPU. 168 * 169 * @par Support System: 170 * linux. 171 */ 172 void osal_kthread_bind(osal_task *task, unsigned int cpu); 173 174 /** 175 * @ingroup osal_task 176 * @brief Lock the task scheduling. 177 * 178 * @par Description: 179 * This API is used to lock the task scheduling. Task switching will not occur if the task scheduling is locked. 180 * 181 * @attention 182 * If the task scheduling is locked, but interrupts are not disabled, tasks are still able to be interrupted. 183 * One is added to the number of task scheduling locks if this API is called. The number of locks is decreased by 184 * one if the task scheduling is unlocked. Therefore, this API should be used together with osal_kthread_unlock. 185 * 186 * @par Support System: 187 * liteos freertos . 188 */ 189 void osal_kthread_lock(void); 190 191 /** 192 * @ingroup osal_task 193 * @brief Unlock the task scheduling. 194 * 195 * @par Description: 196 * This API is used to unlock the task scheduling. Calling this API will decrease the number of task locks by one. 197 * If a task is locked more than once, the task scheduling will be unlocked only when the number of locks becomes zero. 198 * 199 * @attention 200 * The number of locks is decreased by one if this API is called. One is added to the number of task scheduling 201 * locks if the task scheduling is locked. Therefore, this API should be used together with osal_kthread_lock. 202 * 203 * @par Support System: 204 * liteos freertos. 205 */ 206 void osal_kthread_unlock(void); 207 208 /** 209 * @ingroup osal_task 210 * 211 * @brief Used to destroy the threads you created. 212 * 213 * @par Description: 214 * Stops a specified kernel thread. 215 * 216 * @attention osal_kthread_destroy will free memory of task, caller should clear pointer to be NULL. 217 * Note that if you want to destroy a thread, the thread cannot end before calling this function, 218 * Or something terrible will happen. 219 * When you call the Kthread_stop function, the thread function cannot be finished, otherwise it will oops. 220 * task may be free in api, task should be from osal_kthread_create. 221 * 222 * @param task [in] Threads you want to destroy. 223 * @param stop_flag [in] Indicates whether the current thread exits. If the value of stop_flag is 0, 224 * The current thread does not exit. The stop flag is not 0. 225 * 226 * @par Support System: 227 * linux liteos freertos. 228 */ 229 void osal_kthread_destroy(osal_task *task, unsigned int stop_flag); 230 231 /** 232 * @ingroup osal_task 233 * 234 * @brief In this state, it cannot be woken up by an external signal and can only be woken up by the kernel itself. 235 * 236 * @par Description: 237 * The current thread enters the Task_UNINTERRUPTIBLE state and cannot be woken up by external signals. 238 * The kernel wakes up the thread when the sleep time arrives. 239 * 240 * @param sleep_ns [in] Sleep time, units is nanosecond(ns). 241 * 242 * @par Support System: 243 * linux. 244 */ 245 void osal_kthread_schedule(unsigned int sleep_ns); 246 247 /** 248 * @ingroup osal_task 249 * 250 * @brief Set the current thread to the Task_UNINTERRUPTIBLE state. 251 * 252 * @par Description: 253 * In this state, it cannot be woken up by an external signal and can only be woken up by the kernel itself. 254 * 255 * @par Support System: 256 * linux. 257 */ 258 void osal_kthread_set_uninterrupt(void); 259 260 /** 261 * @ingroup osal_task 262 * 263 * @brief Set the current thread status to TASK_RUNNING. 264 * 265 * @par Description: 266 * The fact that the process is runnable does not mean that the process has actually been allocd to the CPU, 267 * it may wait until the scheduler selects it. 268 * This state simply ensures that the process can run as soon as it is selected by the CPU, 269 * without waiting for an external event. 270 * 271 * @par Support System: 272 * linux. 273 */ 274 void osal_kthread_set_running(void); 275 276 /** 277 * @ingroup osal_task 278 * 279 * @brief Programs running in kernel mode can call osal_cond_resched to actively give up CPU resources. 280 * 281 * @par Description: 282 * This prevents soft lockup or long scheduling delay caused by the program running in kernel mode for a long time. 283 * 284 * @par Support System: 285 * linux. 286 */ 287 void osal_cond_resched(void); 288 289 /** 290 * @ingroup osal_task 291 * @brief This function put the current task back to the ready queue and try to do the schedule. 292 * 293 * @par Description: 294 * This function put the current task back to the ready queue and try to do the schedule. 295 * 296 * 297 * @par Support System: 298 * linux liteos freertos. 299 */ 300 void osal_schedule(void); 301 302 /** 303 * @ingroup osal_task 304 * @brief Enabling NEON Algorithm Acceleration. 305 * 306 * @par Description: 307 * Enabling NEON Algorithm Acceleration. 308 * 309 * @attention 310 * This interface work only when CONFIG_KERNEL_MODE_NEON is defined, Otherwise do nothing. 311 * 312 * @par Support System: 313 * linux. 314 */ 315 void osal_kneon_begin(void); 316 317 /** 318 * @ingroup osal_task 319 * @brief Disable NEON Algorithm Acceleration. 320 * 321 * @par Description: 322 * Disable NEON Algorithm Acceleration. 323 * 324 * @attention 325 * This interface work only when CONFIG_KERNEL_MODE_NEON is defined, Otherwise do nothing. 326 * 327 * @par Support System: 328 * linux. 329 */ 330 void osal_kneon_end(void); 331 332 /** 333 * @ingroup osal_task 334 * 335 * @brief Pause the current thread. 336 * 337 * @par Description: 338 * The time slice of the CPU of the current thread is released 339 * so that the running thread becomes ready again and contends for the scheduling right of the CPU again. 340 * It may be obtained, or it may be obtained by other threads. 341 * 342 * @par Support System: 343 * linux freertos. 344 */ 345 void osal_yield(void); 346 347 /** 348 * @ingroup osal_task 349 * 350 * @brief Obtains the pid of the current thread. 351 * 352 * @par Description: 353 * Obtains the pid of the current thread. 354 * 355 * @return pid of the current thread. 356 * 357 * @par Support System: 358 * linux liteos. 359 */ 360 long osal_get_current_pid(void); 361 362 /** 363 * @ingroup osal_task 364 * 365 * @brief Obtains the tid of the current thread. 366 * 367 * @par Description: 368 * Obtains the tid of the current thread. 369 * 370 * @return tid of the current thread. 371 * 372 * @par Support System: 373 * linux liteos seliteos. 374 */ 375 long osal_get_current_tid(void); 376 377 /** 378 * @ingroup osal_task 379 * 380 * @brief Obtains the tgid of the current thread. 381 * 382 * @par Description: 383 * Obtains the tgid of the current thread. 384 * 385 * @return tgid of the current thread. 386 * 387 * @par Support System: 388 * linux. 389 */ 390 int osal_get_current_tgid(void); 391 392 /** 393 * @ingroup osal_task 394 * 395 * @brief Obtains the name of a thread. 396 * 397 * @par Description: 398 * Obtains the name of a thread. 399 * 400 * @return name of the current thread. 401 * 402 * @par Support System: 403 * linux. 404 */ 405 char *osal_get_current_taskname(void); 406 407 /** 408 * @ingroup osal_task 409 * @brief sleep. 410 * 411 * @par Description: 412 * sleep. 413 * 414 * @param msecs [in] Time in milliseconds to sleep for. 415 * 416 * @return Returns 0 when the timer has expired otherwise the remaining time in ms will be returned. 417 * 418 * @par Support System: 419 * linux liteos freertos. 420 */ 421 unsigned long osal_msleep(unsigned int msecs); 422 423 /** 424 * @ingroup osal_task 425 * @brief sleep safely even with waitqueue interruptions. 426 * 427 * @par Description: 428 * sleep safely even with waitqueue interruptions. 429 * 430 * @param msecs [in] Time in milliseconds to sleep for. 431 * 432 * @par Support System: 433 * linux liteos. 434 */ 435 void osal_msleep_uninterruptible(unsigned int msecs); 436 437 /** 438 * @ingroup osal_task 439 * @brief spinning-delay in microsecond (us). 440 * 441 * @par Description: 442 * This API is used to delay in microsecond. 443 * 444 * @param usecs [in] Time in microseconds to wait for. 445 * 446 * @par Support System: 447 * linux liteos freertos. 448 */ 449 void osal_udelay(unsigned int usecs); 450 451 /** 452 * @ingroup osal_task 453 * @brief spinning-delay in millisecond (ms). 454 * 455 * @par Description: 456 * This API is used to delay in millisecond. 457 * 458 * @param msecs [in] Time in milliseconds to wait for. 459 * 460 * @par Support System: 461 * linux liteos freertos. 462 */ 463 void osal_mdelay(unsigned int msecs); 464 465 /** 466 * @ingroup osal_task 467 * @brief Suspend a task. 468 * 469 * @par Description: 470 * This API is used to suspend a specified task, and the task will be removed from the queue of ready tasks. 471 * 472 * @param task [in] Thread to be suspended. 473 * 474 * @par Support System: 475 * liteos. 476 */ 477 void osal_kthread_suspend(osal_task *task); 478 479 /** 480 * @ingroup osal_task 481 * @brief Resume a task. 482 * 483 * @par Description: 484 * This API is used to resume a suspended task. 485 * 486 * @param task [in] Thread to be resumed. 487 * 488 * @par Support System: 489 * liteos. 490 */ 491 void osal_kthread_resume(osal_task *task); 492 493 #ifdef __cplusplus 494 #if __cplusplus 495 } 496 #endif 497 #endif 498 #endif /* __OSAL_TASK_H__ */ 499