1 /* SPDX-License-Identifier: GPL-2.0+ */
2 /*
3 * Copyright 2025 Linaro Limited
4 */
5
6 #include <linux/list.h>
7 #include <linux/types.h>
8 #include <setjmp.h>
9
10 #ifndef _UTHREAD_H_
11 #define _UTHREAD_H_
12
13 /**
14 * DOC: Overview
15 *
16 * The uthread framework is a basic task scheduler that allows to run functions
17 * "in parallel" on a single CPU core. The scheduling is cooperative, not
18 * preemptive -- meaning that context switches from one task to another task is
19 * voluntary, via a call to uthread_schedule(). This characteristic makes thread
20 * synchronization much easier, because a thread cannot be interrupted in the
21 * middle of a critical section (reading from or writing to shared state, for
22 * instance).
23 *
24 * CONFIG_UTHREAD in lib/Kconfig enables the uthread framework. When disabled,
25 * the uthread_create() and uthread_schedule() functions may still be used so
26 * that code differences between uthreads enabled and disabled can be reduced to
27 * a minimum.
28 */
29
30 /**
31 * struct uthread - a thread object
32 *
33 * @fn: thread entry point
34 * @arg: argument passed to the entry point when the thread is started
35 * @ctx: context to resume execution of this thread (via longjmp())
36 * @stack: initial stack pointer for the thread
37 * @done: true once @fn has returned, false otherwise
38 * @grp_id: user-supplied identifier for this thread and possibly others. A
39 * thread can belong to zero or one group (not more), and a group may contain
40 * any number of threads.
41 * @list: link in the global scheduler list
42 */
43 struct uthread {
44 void (*fn)(void *arg);
45 void *arg;
46 jmp_buf ctx;
47 void *stack;
48 bool done;
49 unsigned int grp_id;
50 struct list_head list;
51 };
52
53 /**
54 * enum uthread_mutex_state - internal state of a struct uthread_mutex
55 *
56 * @UTHREAD_MUTEX_UNLOCKED: mutex has no owner
57 * @UTHREAD_MUTEX_LOCKED: mutex has one owner
58 */
59 enum uthread_mutex_state {
60 UTHREAD_MUTEX_UNLOCKED = 0,
61 UTHREAD_MUTEX_LOCKED = 1
62 };
63
64 /**
65 * struct uthread_mutex - a mutex object
66 *
67 * @state: the internal state of the mutex
68 */
69 struct uthread_mutex {
70 enum uthread_mutex_state state;
71 };
72
73 #define UTHREAD_MUTEX_INITIALIZER { .state = UTHREAD_MUTEX_UNLOCKED }
74
75 #ifdef CONFIG_UTHREAD
76
77 /**
78 * uthread_create() - Create a uthread object and make it ready for execution
79 *
80 * Threads are automatically deleted when they return from their entry point.
81 *
82 * @uthr: a pointer to a user-allocated uthread structure to store information
83 * about the new thread, or NULL to let the framework allocate and manage its
84 * own structure.
85 * @fn: the thread's entry point
86 * @arg: argument passed to the thread's entry point
87 * @stack_sz: stack size for the new thread (in bytes). The stack is allocated
88 * on the heap.
89 * @grp_id: an optional thread group ID that the new thread should belong to
90 * (zero for no group)
91 */
92 int uthread_create(struct uthread *uthr, void (*fn)(void *), void *arg,
93 size_t stack_sz, unsigned int grp_id);
94 /**
95 * uthread_schedule() - yield the CPU to the next runnable thread
96 *
97 * This function is called either by the main thread or any secondary thread
98 * (that is, any thread created via uthread_create()) to switch execution to
99 * the next runnable thread.
100 *
101 * Return: true if a thread was scheduled, false if no runnable thread was found
102 */
103 bool uthread_schedule(void);
104 /**
105 * uthread_grp_new_id() - return a new ID for a thread group
106 *
107 * Return: the new thread group ID
108 */
109 unsigned int uthread_grp_new_id(void);
110 /**
111 * uthread_grp_done() - test if all threads in a group are done
112 *
113 * @grp_id: the ID of the thread group that should be considered
114 * Return: false if the group contains at least one runnable thread (i.e., one
115 * thread which entry point has not returned yet), true otherwise
116 */
117 bool uthread_grp_done(unsigned int grp_id);
118
119 /**
120 * uthread_mutex_lock() - lock a mutex
121 *
122 * If the cwmutexlock is available (i.e., not owned by any other thread), then
123 * it is locked for use by the current thread. Otherwise the current thread
124 * blocks: it enters a wait loop by scheduling other threads until the mutex
125 * becomes unlocked.
126 *
127 * @mutex: pointer to the mutex to lock
128 * Return: 0 on success, in which case the lock is owned by the calling thread.
129 * != 0 otherwise (the lock is not owned by the calling thread).
130 */
131 int uthread_mutex_lock(struct uthread_mutex *mutex);
132
133 /**
134 * uthread_mutex_trylock() - lock a mutex if not currently locked
135 *
136 * Similar to uthread_mutex_lock() except return immediately if the mutex is
137 * locked already.
138 *
139 * @mutex: pointer to the mutex to lock
140 * Return: 0 on success, in which case the lock is owned by the calling thread.
141 * EBUSY if the mutex is already locked by another thread. Any other non-zero
142 * value on error.
143 */
144 int uthread_mutex_trylock(struct uthread_mutex *mutex);
145
146 /**
147 * uthread_mutex_unlock() - unlock a mutex
148 *
149 * The mutex is assumed to be owned by the calling thread on entry. On exit, it
150 * is unlocked.
151 *
152 * @mutex: pointer to the mutex to unlock
153 * Return: 0 on success, != 0 on error
154 */
155 int uthread_mutex_unlock(struct uthread_mutex *mutex);
156
157 #else
158
uthread_create(struct uthread * uthr,void (* fn)(void *),void * arg,size_t stack_sz,unsigned int grp_id)159 static inline int uthread_create(struct uthread *uthr, void (*fn)(void *),
160 void *arg, size_t stack_sz,
161 unsigned int grp_id)
162 {
163 fn(arg);
164 return 0;
165 }
166
uthread_schedule(void)167 static inline bool uthread_schedule(void)
168 {
169 return false;
170 }
171
uthread_grp_new_id(void)172 static inline unsigned int uthread_grp_new_id(void)
173 {
174 return 0;
175 }
176
uthread_grp_done(unsigned int grp_id)177 static inline bool uthread_grp_done(unsigned int grp_id)
178 {
179 return true;
180 }
181
182 /* These are macros for convenience on the caller side */
183 #define uthread_mutex_lock(_mutex) ({ 0; })
184 #define uthread_mutex_trylock(_mutex) ({ 0 })
185 #define uthread_mutex_unlock(_mutex) ({ 0; })
186
187 #endif /* CONFIG_UTHREAD */
188 #endif /* _UTHREAD_H_ */
189