include/uthread.h

/* SPDX-License-Identifier: GPL-2.0+ */
/*
 * Copyright 2025 Linaro Limited
 */

#include <linux/list.h>
#include <linux/types.h>
#include <setjmp.h>

#ifndef _UTHREAD_H_
#define _UTHREAD_H_

/**
 * DOC: Overview
 *
 * The uthread framework is a basic task scheduler that allows to run functions
 * "in parallel" on a single CPU core. The scheduling is cooperative, not
 * preemptive -- meaning that context switches from one task to another task is
 * voluntary, via a call to uthread_schedule(). This characteristic makes thread
 * synchronization much easier, because a thread cannot be interrupted in the
 * middle of a critical section (reading from or writing to shared state, for
 * instance).
 *
 * CONFIG_UTHREAD in lib/Kconfig enables the uthread framework. When disabled,
 * the uthread_create()  and uthread_schedule() functions may still be used so
 * that code differences between uthreads enabled and disabled can be reduced to
 * a minimum.
 */

/**
 * struct uthread - a thread object
 *
 * @fn: thread entry point
 * @arg: argument passed to the entry point when the thread is started
 * @ctx: context to resume execution of this thread (via longjmp())
 * @stack: initial stack pointer for the thread
 * @done: true once @fn has returned, false otherwise
 * @grp_id: user-supplied identifier for this thread and possibly others. A
 * thread can belong to zero or one group (not more), and a group may contain
 * any number of threads.
 * @list: link in the global scheduler list
 */
struct uthread {
	void (*fn)(void *arg);
	void *arg;
	jmp_buf ctx;
	void *stack;
	bool done;
	unsigned int grp_id;
	struct list_head list;
};

#ifdef CONFIG_UTHREAD

/**
 * uthread_create() - Create a uthread object and make it ready for execution
 *
 * Threads are automatically deleted when they return from their entry point.
 *
 * @uthr: a pointer to a user-allocated uthread structure to store information
 * about the new thread, or NULL to let the framework allocate and manage its
 * own structure.
 * @fn: the thread's entry point
 * @arg: argument passed to the thread's entry point
 * @stack_sz: stack size for the new thread (in bytes). The stack is allocated
 * on the heap.
 * @grp_id: an optional thread group ID that the new thread should belong to
 * (zero for no group)
 */
int uthread_create(struct uthread *uthr, void (*fn)(void *), void *arg,
		   size_t stack_sz, unsigned int grp_id);
/**
 * uthread_schedule() - yield the CPU to the next runnable thread
 *
 * This function is called either by the main thread or any secondary thread
 * (that is, any thread created via uthread_create()) to switch execution to
 * the next runnable thread.
 *
 * Return: true if a thread was scheduled, false if no runnable thread was found
 */
bool uthread_schedule(void);
/**
 * uthread_grp_new_id() - return a new ID for a thread group
 *
 * Return: the new thread group ID
 */
unsigned int uthread_grp_new_id(void);
/**
 * uthread_grp_done() - test if all threads in a group are done
 *
 * @grp_id: the ID of the thread group that should be considered
 * Return: false if the group contains at least one runnable thread (i.e., one
 * thread which entry point has not returned yet), true otherwise
 */
bool uthread_grp_done(unsigned int grp_id);

#else

static inline int uthread_create(struct uthread *uthr, void (*fn)(void *),
				 void *arg, size_t stack_sz,
				 unsigned int grp_id)
{
	fn(arg);
	return 0;
}

static inline bool uthread_schedule(void)
{
	return false;
}

static inline unsigned int uthread_grp_new_id(void)
{
	return 0;
}

static inline bool uthread_grp_done(unsigned int grp_id)
{
	return true;
}

#endif /* CONFIG_UTHREAD */
#endif /* _UTHREAD_H_ */