1 /* 2 * Copyright (c) 2017 Intel Corporation 3 * 4 * SPDX-License-Identifier: Apache-2.0 5 */ 6 7 #ifndef ZEPHYR_INCLUDE_POSIX_PTHREAD_H_ 8 #define ZEPHYR_INCLUDE_POSIX_PTHREAD_H_ 9 10 #include <stdlib.h> 11 #include <string.h> 12 13 #include <zephyr/kernel.h> 14 #include <zephyr/posix/time.h> 15 #include <zephyr/posix/unistd.h> 16 #include <zephyr/posix/sched.h> 17 18 #ifdef __cplusplus 19 extern "C" { 20 #endif 21 22 /* 23 * Pthread detach/joinable 24 * Undefine possibly predefined values by external toolchain headers 25 */ 26 #undef PTHREAD_CREATE_DETACHED 27 #define PTHREAD_CREATE_DETACHED 1 28 #undef PTHREAD_CREATE_JOINABLE 29 #define PTHREAD_CREATE_JOINABLE 0 30 31 /* Pthread resource visibility */ 32 #define PTHREAD_PROCESS_PRIVATE 0 33 #define PTHREAD_PROCESS_SHARED 1 34 35 /* Pthread cancellation */ 36 #define PTHREAD_CANCELED ((void *)-1) 37 #define PTHREAD_CANCEL_ENABLE 0 38 #define PTHREAD_CANCEL_DISABLE 1 39 #define PTHREAD_CANCEL_DEFERRED 0 40 #define PTHREAD_CANCEL_ASYNCHRONOUS 1 41 42 /* Pthread scope */ 43 #undef PTHREAD_SCOPE_PROCESS 44 #define PTHREAD_SCOPE_PROCESS 1 45 #undef PTHREAD_SCOPE_SYSTEM 46 #define PTHREAD_SCOPE_SYSTEM 0 47 48 /* Pthread inherit scheduler */ 49 #undef PTHREAD_INHERIT_SCHED 50 #define PTHREAD_INHERIT_SCHED 0 51 #undef PTHREAD_EXPLICIT_SCHED 52 #define PTHREAD_EXPLICIT_SCHED 1 53 54 /* Passed to pthread_once */ 55 #define PTHREAD_ONCE_INIT {0} 56 57 /* The minimum allowable stack size */ 58 #define PTHREAD_STACK_MIN K_KERNEL_STACK_LEN(0) 59 60 /** 61 * @brief Declare a condition variable as initialized 62 * 63 * Initialize a condition variable with the default condition variable attributes. 64 */ 65 #define PTHREAD_COND_INITIALIZER (-1) 66 67 /** 68 * @brief POSIX threading compatibility API 69 * 70 * See IEEE 1003.1 71 */ 72 int pthread_cond_init(pthread_cond_t *cv, const pthread_condattr_t *att); 73 74 /** 75 * @brief POSIX threading compatibility API 76 * 77 * See IEEE 1003.1 78 */ 79 int pthread_cond_destroy(pthread_cond_t *cv); 80 81 /** 82 * @brief POSIX threading compatibility API 83 * 84 * See IEEE 1003.1 85 */ 86 int pthread_cond_signal(pthread_cond_t *cv); 87 88 /** 89 * @brief POSIX threading compatibility API 90 * 91 * See IEEE 1003.1 92 */ 93 int pthread_cond_broadcast(pthread_cond_t *cv); 94 95 /** 96 * @brief POSIX threading compatibility API 97 * 98 * See IEEE 1003.1 99 */ 100 int pthread_cond_wait(pthread_cond_t *cv, pthread_mutex_t *mut); 101 102 /** 103 * @brief POSIX threading compatibility API 104 * 105 * See IEEE 1003.1 106 */ 107 int pthread_cond_timedwait(pthread_cond_t *cv, pthread_mutex_t *mut, 108 const struct timespec *abstime); 109 110 /** 111 * @brief POSIX threading compatibility API 112 * 113 * See IEEE 1003.1. 114 * 115 */ 116 int pthread_condattr_init(pthread_condattr_t *att); 117 118 /** 119 * @brief POSIX threading compatibility API 120 * 121 * See IEEE 1003.1 122 * 123 */ 124 int pthread_condattr_destroy(pthread_condattr_t *att); 125 126 /** 127 * @brief POSIX threading compatibility API 128 * 129 * See IEEE 1003.1 130 * 131 */ 132 int pthread_condattr_getclock(const pthread_condattr_t *ZRESTRICT att, 133 clockid_t *ZRESTRICT clock_id); 134 135 /** 136 * @brief POSIX threading compatibility API 137 * 138 * See IEEE 1003.1 139 * 140 */ 141 142 int pthread_condattr_setclock(pthread_condattr_t *att, clockid_t clock_id); 143 144 /** 145 * @brief Declare a mutex as initialized 146 * 147 * Initialize a mutex with the default mutex attributes. 148 */ 149 #define PTHREAD_MUTEX_INITIALIZER (-1) 150 151 /** 152 * @brief Declare a rwlock as initialized 153 * 154 * Initialize a rwlock with the default rwlock attributes. 155 */ 156 #define PTHREAD_RWLOCK_INITIALIZER (-1) 157 158 /* 159 * Mutex attributes - type 160 * 161 * PTHREAD_MUTEX_NORMAL: Owner of mutex cannot relock it. Attempting 162 * to relock will cause deadlock. 163 * PTHREAD_MUTEX_RECURSIVE: Owner can relock the mutex. 164 * PTHREAD_MUTEX_ERRORCHECK: If owner attempts to relock the mutex, an 165 * error is returned. 166 * 167 */ 168 #define PTHREAD_MUTEX_NORMAL 0 169 #define PTHREAD_MUTEX_RECURSIVE 1 170 #define PTHREAD_MUTEX_ERRORCHECK 2 171 #define PTHREAD_MUTEX_DEFAULT PTHREAD_MUTEX_NORMAL 172 173 /* 174 * Mutex attributes - protocol 175 * 176 * PTHREAD_PRIO_NONE: Ownership of mutex does not affect priority. 177 * PTHREAD_PRIO_INHERIT: Owner's priority is boosted to the priority of 178 * highest priority thread blocked on the mutex. 179 * PTHREAD_PRIO_PROTECT: Mutex has a priority ceiling. The owner's 180 * priority is boosted to the highest priority ceiling of all mutexes 181 * owned (regardless of whether or not other threads are blocked on 182 * any of these mutexes). 183 * FIXME: Only PRIO_NONE is supported. Implement other protocols. 184 */ 185 #define PTHREAD_PRIO_NONE 0 186 #define PTHREAD_PRIO_INHERIT 1 187 #define PTHREAD_PRIO_PROTECT 2 188 189 /** 190 * @brief POSIX threading compatibility API 191 * 192 * See IEEE 1003.1 193 */ 194 int pthread_mutex_destroy(pthread_mutex_t *m); 195 196 /** 197 * @brief POSIX threading compatibility API 198 * 199 * See IEEE 1003.1 200 */ 201 int pthread_mutex_lock(pthread_mutex_t *m); 202 203 /** 204 * @brief POSIX threading compatibility API 205 * 206 * See IEEE 1003.1 207 */ 208 int pthread_mutex_unlock(pthread_mutex_t *m); 209 210 /** 211 * @brief POSIX threading compatibility API 212 * 213 * See IEEE 1003.1 214 */ 215 216 int pthread_mutex_timedlock(pthread_mutex_t *m, 217 const struct timespec *abstime); 218 219 /** 220 * @brief POSIX threading compatibility API 221 * 222 * See IEEE 1003.1 223 */ 224 int pthread_mutex_trylock(pthread_mutex_t *m); 225 226 /** 227 * @brief POSIX threading compatibility API 228 * 229 * See IEEE 1003.1 230 */ 231 int pthread_mutex_init(pthread_mutex_t *m, 232 const pthread_mutexattr_t *att); 233 234 /** 235 * @brief POSIX threading compatibility API 236 * 237 * See IEEE 1003.1 238 */ 239 int pthread_mutexattr_setprotocol(pthread_mutexattr_t *attr, int protocol); 240 241 /** 242 * @brief POSIX threading compatibility API 243 * 244 * See IEEE 1003.1 245 */ 246 int pthread_mutexattr_settype(pthread_mutexattr_t *attr, int type); 247 248 /** 249 * @brief POSIX threading compatibility API 250 * 251 * See IEEE 1003.1 252 */ 253 int pthread_mutexattr_getprotocol(const pthread_mutexattr_t *attr, 254 int *protocol); 255 256 /** 257 * @brief POSIX threading compatibility API 258 * 259 * See IEEE 1003.1 260 */ 261 int pthread_mutexattr_gettype(const pthread_mutexattr_t *attr, int *type); 262 263 /** 264 * @brief POSIX threading compatibility API 265 * 266 * See IEEE 1003.1 267 * 268 * Note that pthread attribute structs are currently noops in Zephyr. 269 */ 270 int pthread_mutexattr_init(pthread_mutexattr_t *attr); 271 272 /** 273 * @brief POSIX threading compatibility API 274 * 275 * See IEEE 1003.1 276 * 277 * Note that pthread attribute structs are currently noops in Zephyr. 278 */ 279 int pthread_mutexattr_destroy(pthread_mutexattr_t *attr); 280 281 #define PTHREAD_BARRIER_SERIAL_THREAD 1 282 283 /* 284 * Barrier attributes - type 285 */ 286 #define PTHREAD_PROCESS_PRIVATE 0 287 #define PTHREAD_PROCESS_PUBLIC 1 288 289 /** 290 * @brief POSIX threading compatibility API 291 * 292 * See IEEE 1003.1 293 */ 294 int pthread_barrier_wait(pthread_barrier_t *b); 295 296 /** 297 * @brief POSIX threading compatibility API 298 * 299 * See IEEE 1003.1 300 */ 301 int pthread_barrier_init(pthread_barrier_t *b, const pthread_barrierattr_t *attr, 302 unsigned int count); 303 304 /** 305 * @brief POSIX threading compatibility API 306 * 307 * See IEEE 1003.1 308 */ 309 int pthread_barrier_destroy(pthread_barrier_t *b); 310 311 /** 312 * @brief POSIX threading compatibility API 313 * 314 * See IEEE 1003.1 315 */ 316 int pthread_barrierattr_init(pthread_barrierattr_t *b); 317 318 /** 319 * @brief POSIX threading compatibility API 320 * 321 * See IEEE 1003.1 322 */ 323 int pthread_barrierattr_destroy(pthread_barrierattr_t *b); 324 325 /** 326 * @brief POSIX threading compatibility API 327 * 328 * See IEEE 1003.1 329 */ 330 int pthread_barrierattr_setpshared(pthread_barrierattr_t *attr, int pshared); 331 332 /** 333 * @brief POSIX threading compatibility API 334 * 335 * See IEEE 1003.1 336 */ 337 int pthread_barrierattr_getpshared(const pthread_barrierattr_t *ZRESTRICT attr, 338 int *ZRESTRICT pshared); 339 340 /* Predicates and setters for various pthread attribute values that we 341 * don't support (or always support: the "process shared" attribute 342 * can only be true given the way Zephyr implements these 343 * objects). Leave these undefined for simplicity instead of defining 344 * stubs to return an error that would have to be logged and 345 * interpreted just to figure out that we didn't support it in the 346 * first place. These APIs are very rarely used even in production 347 * Unix code. Leave the declarations here so they can be easily 348 * uncommented and implemented as needed. 349 350 int pthread_condattr_getpshared(const pthread_condattr_t * int *); 351 int pthread_condattr_setpshared(pthread_condattr_t *, int); 352 int pthread_mutex_consistent(pthread_mutex_t *); 353 int pthread_mutexattr_getpshared(const pthread_mutexattr_t * int *); 354 int pthread_mutexattr_getrobust(const pthread_mutexattr_t * int *); 355 int pthread_mutexattr_setpshared(pthread_mutexattr_t *, int); 356 int pthread_mutexattr_setrobust(pthread_mutexattr_t *, int); 357 */ 358 359 #ifdef CONFIG_POSIX_THREAD_PRIO_PROTECT 360 int pthread_mutex_getprioceiling(const pthread_mutex_t *ZRESTRICT mutex, 361 int *ZRESTRICT prioceiling); 362 int pthread_mutex_setprioceiling(pthread_mutex_t *ZRESTRICT mutex, int prioceiling, 363 int *ZRESTRICT old_ceiling); 364 int pthread_mutexattr_getprioceiling(const pthread_mutexattr_t *ZRESTRICT attr, 365 int *ZRESTRICT prioceiling); 366 int pthread_mutexattr_setprioceiling(pthread_mutexattr_t *attr, int prioceiling); 367 #endif /* CONFIG_POSIX_THREAD_PRIO_PROTECT */ 368 369 /* Base Pthread related APIs */ 370 371 /** 372 * @brief Obtain ID of the calling thread. 373 * 374 * The results of calling this API from threads not created with 375 * pthread_create() are undefined. 376 * 377 * See IEEE 1003.1 378 */ 379 pthread_t pthread_self(void); 380 381 /** 382 * @brief Compare thread IDs. 383 * 384 * See IEEE 1003.1 385 */ 386 int pthread_equal(pthread_t pt1, pthread_t pt2); 387 388 /** 389 * @brief Destroy the read-write lock attributes object. 390 * 391 * See IEEE 1003.1 392 */ 393 int pthread_rwlockattr_destroy(pthread_rwlockattr_t *attr); 394 395 /** 396 * @brief initialize the read-write lock attributes object. 397 * 398 * See IEEE 1003.1 399 */ 400 int pthread_rwlockattr_init(pthread_rwlockattr_t *attr); 401 402 int pthread_rwlockattr_getpshared(const pthread_rwlockattr_t *ZRESTRICT attr, 403 int *ZRESTRICT pshared); 404 int pthread_rwlockattr_setpshared(pthread_rwlockattr_t *attr, int pshared); 405 406 int pthread_attr_getguardsize(const pthread_attr_t *ZRESTRICT attr, size_t *ZRESTRICT guardsize); 407 int pthread_attr_getstacksize(const pthread_attr_t *attr, size_t *stacksize); 408 int pthread_attr_setguardsize(pthread_attr_t *attr, size_t guardsize); 409 int pthread_attr_setstacksize(pthread_attr_t *attr, size_t stacksize); 410 int pthread_attr_setschedpolicy(pthread_attr_t *attr, int policy); 411 int pthread_attr_getschedpolicy(const pthread_attr_t *attr, int *policy); 412 int pthread_attr_setdetachstate(pthread_attr_t *attr, int detachstate); 413 int pthread_attr_getdetachstate(const pthread_attr_t *attr, int *detachstate); 414 int pthread_attr_init(pthread_attr_t *attr); 415 int pthread_attr_destroy(pthread_attr_t *attr); 416 int pthread_attr_getschedparam(const pthread_attr_t *attr, 417 struct sched_param *schedparam); 418 int pthread_getschedparam(pthread_t pthread, int *policy, 419 struct sched_param *param); 420 int pthread_attr_getstack(const pthread_attr_t *attr, 421 void **stackaddr, size_t *stacksize); 422 int pthread_attr_setstack(pthread_attr_t *attr, void *stackaddr, 423 size_t stacksize); 424 int pthread_attr_getscope(const pthread_attr_t *attr, int *contentionscope); 425 int pthread_attr_setscope(pthread_attr_t *attr, int contentionscope); 426 int pthread_attr_getinheritsched(const pthread_attr_t *attr, int *inheritsched); 427 int pthread_attr_setinheritsched(pthread_attr_t *attr, int inheritsched); 428 #ifdef CONFIG_POSIX_THREADS 429 int pthread_once(pthread_once_t *once, void (*initFunc)(void)); 430 #endif 431 FUNC_NORETURN void pthread_exit(void *retval); 432 int pthread_timedjoin_np(pthread_t thread, void **status, const struct timespec *abstime); 433 int pthread_tryjoin_np(pthread_t thread, void **status); 434 int pthread_join(pthread_t thread, void **status); 435 int pthread_cancel(pthread_t pthread); 436 int pthread_detach(pthread_t thread); 437 int pthread_create(pthread_t *newthread, const pthread_attr_t *attr, 438 void *(*threadroutine)(void *), void *arg); 439 int pthread_setcancelstate(int state, int *oldstate); 440 int pthread_setcanceltype(int type, int *oldtype); 441 void pthread_testcancel(void); 442 int pthread_attr_setschedparam(pthread_attr_t *attr, 443 const struct sched_param *schedparam); 444 int pthread_setschedparam(pthread_t pthread, int policy, 445 const struct sched_param *param); 446 int pthread_setschedprio(pthread_t thread, int prio); 447 int pthread_rwlock_destroy(pthread_rwlock_t *rwlock); 448 int pthread_rwlock_init(pthread_rwlock_t *rwlock, 449 const pthread_rwlockattr_t *attr); 450 int pthread_rwlock_rdlock(pthread_rwlock_t *rwlock); 451 int pthread_rwlock_timedrdlock(pthread_rwlock_t *rwlock, 452 const struct timespec *abstime); 453 int pthread_rwlock_timedwrlock(pthread_rwlock_t *rwlock, 454 const struct timespec *abstime); 455 int pthread_rwlock_tryrdlock(pthread_rwlock_t *rwlock); 456 int pthread_rwlock_trywrlock(pthread_rwlock_t *rwlock); 457 int pthread_rwlock_unlock(pthread_rwlock_t *rwlock); 458 int pthread_rwlock_wrlock(pthread_rwlock_t *rwlock); 459 int pthread_key_create(pthread_key_t *key, 460 void (*destructor)(void *)); 461 int pthread_key_delete(pthread_key_t key); 462 int pthread_setspecific(pthread_key_t key, const void *value); 463 void *pthread_getspecific(pthread_key_t key); 464 int pthread_atfork(void (*prepare)(void), void (*parent)(void), void (*child)(void)); 465 int pthread_getconcurrency(void); 466 int pthread_setconcurrency(int new_level); 467 468 void __z_pthread_cleanup_push(void *cleanup[3], void (*routine)(void *arg), void *arg); 469 void __z_pthread_cleanup_pop(int execute); 470 471 #define pthread_cleanup_push(_rtn, _arg) \ 472 do /* enforce '{'-like behaviour */ { \ 473 void *_z_pthread_cleanup[3]; \ 474 __z_pthread_cleanup_push(_z_pthread_cleanup, _rtn, _arg) 475 476 #define pthread_cleanup_pop(_ex) \ 477 __z_pthread_cleanup_pop(_ex); \ 478 } /* enforce '}'-like behaviour */ while (0) 479 480 /* Glibc / Oracle Extension Functions */ 481 482 /** 483 * @brief Set name of POSIX thread. 484 * 485 * Non-portable, extension function that conforms with most 486 * other definitions of this function. 487 * 488 * @param thread POSIX thread to set name 489 * @param name Name string 490 * @retval 0 Success 491 * @retval ESRCH Thread does not exist 492 * @retval EINVAL Name buffer is NULL 493 * @retval Negative value if kernel function error 494 * 495 */ 496 int pthread_setname_np(pthread_t thread, const char *name); 497 498 /** 499 * @brief Get name of POSIX thread and store in name buffer 500 * that is of size len. 501 * 502 * Non-portable, extension function that conforms with most 503 * other definitions of this function. 504 * 505 * @param thread POSIX thread to obtain name information 506 * @param name Destination buffer 507 * @param len Destination buffer size 508 * @retval 0 Success 509 * @retval ESRCH Thread does not exist 510 * @retval EINVAL Name buffer is NULL 511 * @retval Negative value if kernel function error 512 */ 513 int pthread_getname_np(pthread_t thread, char *name, size_t len); 514 515 #ifdef CONFIG_POSIX_THREADS 516 517 /** 518 * @brief Destroy a pthread_spinlock_t. 519 * 520 * See IEEE 1003.1 521 */ 522 int pthread_spin_destroy(pthread_spinlock_t *lock); 523 524 /** 525 * @brief Initialize a thread_spinlock_t. 526 * 527 * See IEEE 1003.1 528 */ 529 int pthread_spin_init(pthread_spinlock_t *lock, int pshared); 530 531 /** 532 * @brief Lock a previously initialized thread_spinlock_t. 533 * 534 * See IEEE 1003.1 535 */ 536 int pthread_spin_lock(pthread_spinlock_t *lock); 537 538 /** 539 * @brief Attempt to lock a previously initialized thread_spinlock_t. 540 * 541 * See IEEE 1003.1 542 */ 543 int pthread_spin_trylock(pthread_spinlock_t *lock); 544 545 /** 546 * @brief Unlock a previously locked thread_spinlock_t. 547 * 548 * See IEEE 1003.1 549 */ 550 int pthread_spin_unlock(pthread_spinlock_t *lock); 551 552 #endif 553 554 #ifdef __cplusplus 555 } 556 #endif 557 558 #endif /* ZEPHYR_INCLUDE_POSIX_PTHREAD_H_ */ 559
