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