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