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