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