/** @file */
// xos_thread.h - XOS Thread API interface and data structures.
// Copyright (c) 2003-2015 Cadence Design Systems, Inc.
//
// Permission is hereby granted, free of charge, to any person obtaining
// a copy of this software and associated documentation files (the
// "Software"), to deal in the Software without restriction, including
// without limitation the rights to use, copy, modify, merge, publish,
// distribute, sublicense, and/or sell copies of the Software, and to
// permit persons to whom the Software is furnished to do so, subject to
// the following conditions:
//
// The above copyright notice and this permission notice shall be included
// in all copies or substantial portions of the Software.
//
// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
// EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
// MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
// IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
// CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
// TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
// SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
// NOTE: Do not include this file directly in your application. Including
// xos.h will automatically include this file.
#ifndef __XOS_THREAD_H__
#define __XOS_THREAD_H__
#ifdef __cplusplus
extern "C" {
#endif
#include "xos_types.h"
#include "xos_params.h"
//-----------------------------------------------------------------------------
// Number of thread priority levels.
//-----------------------------------------------------------------------------
#ifndef XOS_NUM_PRIORITY
#error "XOS_NUM_PRIORITY must be defined (in xos_params.h)."
#endif
#if XOS_NUM_PRIORITY > 32
#error "The number of thread priority levels (XOS_NUM_PRIORITY) must be <= 32."
#endif
#define XOS_MAX_PRIORITY (XOS_NUM_PRIORITY)
//-----------------------------------------------------------------------------
// Macro for thread self pointer.
//-----------------------------------------------------------------------------
#define XOS_THREAD_SELF (xos_thread_id())
//-----------------------------------------------------------------------------
///
/// Thread entry function pointer type.
///
//-----------------------------------------------------------------------------
typedef int32_t (XosThreadFunc)(void * arg, int32_t wake_value);
//-----------------------------------------------------------------------------
// Thread switcher function signature.
//-----------------------------------------------------------------------------
typedef struct XosThread XosThread;
typedef int32_t (XosSwitchFunc)(XosThread *);
//-----------------------------------------------------------------------------
///
/// Condition evaluation callback function pointer type.
///
//-----------------------------------------------------------------------------
typedef int32_t (XosCondFunc)(void * arg, int32_t sig_value, XosThread * thread);
//-----------------------------------------------------------------------------
///
/// Thread exit handler function pointer type.
///
//-----------------------------------------------------------------------------
typedef int32_t (XosThdExitFunc)(int32_t exitcode);
//-----------------------------------------------------------------------------
// Thread queue structure. Used to implement the ready queues as well
// as the wait queues.
//-----------------------------------------------------------------------------
typedef struct XosThreadQueue {
XosThread * head; // Pointer to first thread in queue, or 0 if none.
XosThread ** tail; // Pointer to last thread's r_next pointer, or
// to "head" if none.
} XosThreadQueue;
//-----------------------------------------------------------------------------
// Stack frame for a thread that is not running. That is, it has either
// been preempted or has yielded.
//-----------------------------------------------------------------------------
typedef union XosFrame {
XosExcFrame e; // resume_fn == &xos_resume_preempted_thread
XosCoopFrame c; // resume_fn == &xos_resume_cooperative_thread
// nothing for resume_fn == &xos_resume_idle_thread
// nothing for resume_fn == &xos_resume_by_restart
} XosFrame;
//-----------------------------------------------------------------------------
// Thread Control Block. Tracks the state and control information associated
// with a thread.
//
// IMPORTANT: keep this in sync with TCB_*** offsets in xos_common.h .
//-----------------------------------------------------------------------------
struct XosThread {
XosThread * r_next; // 00 Next thread in queue (eg. ready queue of
// its priority, or some queue of blocked threads)
// Should be NULL if not in any queue.
XosThread ** r_pprev; // 04 Points to previous queue entry's r_next
// pointer (i.e. to itself), or to queue head
// if first in queue. NULL if not in any queue.
XosThread * all_next; // 08 Next in list of all threads.
void * resume_fn; // 12 Pointer to the routine to be called to
// resume this thread. On entry to such code:
// a2 == xos_curr_threadptr (thread being resumed)
// a3 == &xos_globals
XosFrame * esf; // 16 Pointer to saved exception stack frame,
// just below thread's current stack pointer.
// For RTC threads, this is valid only while the
// thread is preempted, not when it is blocked.
void * tie_save; // 20 TIE state save area. May be NULL if there
// is not TIE state saved for this thread.
int32_t wake_value; // 24 Value returned from block call (by wake call)
// (for RTC: pass this to start function??)
XosSwitchFunc * switch_fn; // 28 Pointer to a function that
// can be called from within this thread, to save
// this thread's state and switch to a specified
// other thread. Returns wake value.
void * stack_base; // 32 Base of stack as specified by thread creator.
void * stack_end; // 36 End of stack (adjusted for TIE state save area
// if any).
XosThreadFunc * entry; // 40 Pointer to thread entry function. Used for
// RTC thread restart.
void * arg; // 44 Argument value passed to entry function.
bool ready; // 48 Set when thread is ready to run, and is in
// its priority queue (i.e. r_pprev is set when
// this flag is set).
bool in_exit; // Exit flag, nonzero when in exit processing.
int8_t priority; // Thread priority, 0 .. (XOS_MAX_PRI - 1). Higher
// numbers have higher priority. This must only be
// changed when thread is not ready, or by calling
// xos_thread_set_priority().
int8_t preempt_pri; // This thread's preemption blocking priority.
// (preempt_pri >= priority). A thread's priority
// must be higher than another's preempt_pri to be
// able to preempt it. Note that preempt_pri can
// change during runtime e.g. due to priority
// inheritance.
uint32_t flags; // 52 Thread creation flags.
const char * name; // 56 Thread name (mainly for debug).
const char * block_cause; // 60 Reason for blocking. Valid only when thread
// not ready (r_pprev == 0).
XosThread * container; // 64 Thread whose stack will be used to run
// this thread. Valid for RTC threads only, else NULL.
XosThdExitFunc * exit_func; // 68 Thread exit handler function pointer.
XosThreadQueue exit_waiters; // 72 Queue of threads waiting for this one to exit.
XosThreadQueue * wq_ptr; // 80 If this thread is in a wait queue, this
// points to the queue. Must be NULL when
// thread not in a queue.
XosCondFunc * cond_fn; // 84 Condition function. Valid only while thread
// is blocked on condition.
void * cond_arg; // 88 Argument to be passed to condition function.
uint16_t cp_mask; // 92 Mask of coprocessors used.
uint16_t cp_saved; // 94 Mask of coprocessors saved.
uint32_t event_bits; // 96 event bits
uint32_t event_mask; // 100 event bit mask
uint32_t event_flags; // 104 event flags
void * clib_ptr; // 108 Pointer to C lib context struct.
uint32_t sig; // 112 Signature of valid TCB
uint32_t resume_ccount; // 116 cycle count at resume
uint64_t cycle_count; // 120 number of cycles consumed (approx).
// NOTE: must be 8-byte aligned
uint32_t normal_resumes; // 128 Number of non-preemptive resumptions.
uint32_t preempt_resumes;// 132 Number of preemptive resumptions.
#if XOS_OPT_THREAD_SAFE_CLIB
CLIB_THREAD_STRUCT; // C library context area.
#endif
};
//-----------------------------------------------------------------------------
// User-visible flags for xos_thread_create().
//-----------------------------------------------------------------------------
#define XOS_THREAD_SUSPEND 0x0001 ///< Create suspended instead of ready
#define XOS_THREAD_RTC 0x0002 ///< Run-to-completion thread
#define XOS_THREAD_NO_CP 0x0004 ///< Thread does not use coprocessors
//-----------------------------------------------------------------------------
// Flags used by thread creation extra parameters.
//-----------------------------------------------------------------------------
#define XOS_TP_COPROC_MASK 0x0001
#define XOS_TP_PREEMPT_PRI 0x0002
#define XOS_TP_EXIT_HANDLER 0x0004
//-----------------------------------------------------------------------------
// Thread creation extra parameters.
//-----------------------------------------------------------------------------
typedef struct XosThreadParm {
uint32_t parms_mask; // Combination of XOS_TP_xxx flags indicating
// which parameters are valid.
uint16_t cp_mask; // Mask of coprocessors the thread can access.
uint32_t preempt_pri; // Initial preemption blocking priority. Can be
// changed later via xos_thread_set_priority().
XosThdExitFunc * handler; // Exit handler function.
} XosThreadParm;
//-----------------------------------------------------------------------------
// Wrapper struct for RTC (run to completion) thread.
//-----------------------------------------------------------------------------
typedef struct XosRtcThread {
struct XosThread thread;
} XosRtcThread;
//-----------------------------------------------------------------------------
// External variables.
//-----------------------------------------------------------------------------
extern XosThread * xos_curr_threadptr; // Current active thread
extern XosThread * xos_next_threadptr; // Next ready thread
extern XosThread * xos_all_threads; // List of all threads
//-----------------------------------------------------------------------------
///
/// Set thread creation parameter: the group of coprocessors that this thread
/// will use. This must be set during thread creation, and cannot be changed
/// after the thread has been created. Defining this allows reduction of
/// memory usage (for CP state saving) in some circumstances, and can also
/// speed up the context switch time.
///
/// NOTE: Support for this is not currently implemented. If a thread uses
/// any coprocessor, space for all coprocessors must be reserved.
///
/// \param parms Thread creation parameter structure. Must be
/// allocated by the caller.
///
/// \param cp_mask Bitmask of coprocessors thread is allowed to
/// use. Bit 0 for coprocessor 0, etc.
///
/// \return Returns nothing.
///
//-----------------------------------------------------------------------------
static inline void
xos_threadp_set_cp_mask(XosThreadParm * parms, uint16_t cp_mask)
{
if (parms != XOS_NULL) {
parms->parms_mask |= XOS_TP_COPROC_MASK;
parms->cp_mask = cp_mask;
}
}
//-----------------------------------------------------------------------------
///
/// Set thread creation parameter: thread pre-emption priority.
///
/// \param parms Thread creation parameter structure. Must be
/// allocated by caller.
///
/// \param preempt_pri Thread pre-emption blocking priority.
/// From 0 .. XOS_NUM_PRIORITY - 1.
/// Must be greater or equal to the thread priority
/// (if not, is automatically set to thread priority).
///
/// \return Returns nothing.
///
//-----------------------------------------------------------------------------
static inline void
xos_threadp_set_preemption_priority(XosThreadParm * parms, int8_t preempt_pri)
{
if (parms != XOS_NULL) {
parms->parms_mask |= XOS_TP_PREEMPT_PRI;
parms->preempt_pri = preempt_pri;
}
}
//-----------------------------------------------------------------------------
///
/// Set thread creation parameter: thread exit handler.
///
/// \param parms Thread creation parameter structure. Must be
/// allocated by caller.
///
/// \param handler Exit handler function.
///
/// \return Returns nothing.
//-----------------------------------------------------------------------------
static inline void
xos_threadp_set_exit_handler(XosThreadParm * parms, XosThdExitFunc * handler)
{
if (parms != XOS_NULL) {
parms->parms_mask |= XOS_TP_EXIT_HANDLER;
parms->handler = handler;
}
}
//-----------------------------------------------------------------------------
///
/// Create a new thread. If the thread is not created suspended, then it will
/// be made ready as soon as it is created, and will immediately run if it is
/// the highest priority non-blocked thread in the system.
///
/// \param thread Pointer to the thread descriptor (an otherwise
/// unused XosThread structure, usually allocated
/// by the caller for the lifetime of the thread,
/// for example as a global variable).
///
/// \param container Pointer to separate thread acting as "container"
/// for this one. At the moment, this is only meaningful
/// for run-to-completion (RTC) threads (identified with
/// the XOS_THREAD_RTC flag), in which case the container
/// must have the same priority and also be an RTC thread.
/// (The priority restriction may be lifted in a future
/// implementation, with appropriate constraints on dynamic
/// reprioritization of the created thread).
///
/// \param entry Thread entry function, takes one argument.
///
/// \param arg Argument "void*" that is passed to the thread function.
///
/// \param name Unique name of the thread, for debug/display purposes.
/// This string must be valid for the lifetime of the thread
/// (only a pointer to it is stored in the thread control block).
/// Typically consists of identifier chars with no spaces.
///
/// \param stack Base of initial stack for the thread, allocated by the
/// caller. Need not be aligned (initial stack pointer will be
/// computed and aligned from given stack base and size).
/// Required argument, except for run-to-completion threads
/// when container is non-NULL, in which case the container's
/// stack is used and this argument must be NULL.
///
/// \param stack_size Size of the stack, in bytes.
/// NOTE: stack should be at least XOS_STACK_EXTRA bytes plus
/// whatever the thread actually needs if the thread will use
/// coprocessors/TIE state. If the thread will not touch the
/// coprocessors, then it should be XOS_STACK_EXTRA_NO_CP
/// plus whatever the thread actually needs.
/// Recommended minimum stack sizes are defined by the constants
/// XOS_STACK_MIN_SIZE and XOS_STACK_MIN_SIZE_NO_CP.
///
/// For run-to-completion threads where container is non-NULL,
/// stack_size specifies the minimum stack size required for
/// the thread; it should be smaller or equal to the container's
/// stack.
///
/// \param priority Initial thread priority. From 0 .. XOS_MAX_PRI - 1.
/// Higher numbers are higher priority.
///
/// \param parms Pointer to extra parameters structure, or 0 if none given.
/// Use xos_thread_p_***() functions to set parameters in the
/// structure.
///
/// \param flags Option flags:
/// - XOS_THREAD_SUSPEND -- Leave thread suspended instead of
/// making it ready. The thread can be made ready to run later
/// by calling xos_thread_resume().
/// - XOS_THREAD_RTC -- Run-to-completion thread.
/// - XOS_THREAD_NO_CP -- Thread does not use coprocessors.
/// No coprocessor state will be saved for this thread.
/// Threads that have this flag set will not allocate any
/// storage for saving coprocessor state and so can have
/// smaller stacks.
///
/// NOTE: xos_start_main() calls xos_thread_create() to convert main() into the 'main'
/// thread.
///
/// \return Returns XOS_OK if successful, error code otherwise.
///
//-----------------------------------------------------------------------------
int32_t
xos_thread_create(XosThread * thread,
XosThread * container,
XosThreadFunc * entry,
void * arg,
const char * name,
void * stack,
uint32_t stack_size,
int32_t priority,
XosThreadParm * parms,
uint32_t flags );
//-----------------------------------------------------------------------------
///
/// Remove thread and free up all resources. Thread must have exited already.
/// After this call returns, all resources allocated to the thread (e.g. TCB,
/// stack space, etc.) can be reused.
///
/// \param thread Handle of thread to be deleted.
///
/// \return Returns XOS_OK on success, else error code.
///
/// NOTE: A thread cannot call this on itself.
///
//-----------------------------------------------------------------------------
int32_t
xos_thread_delete(XosThread * thread);
//-----------------------------------------------------------------------------
///
/// Force the thread to terminate. The thread execution is aborted, but exit
/// processing will still happen, i.e. the exit handler (if any) will be run.
/// After termination, any other threads waiting on this thread are notified.
/// This function cannot be called on the current thread.
///
/// \param thread Handle of thread to be aborted.
///
/// \param exitcode Exit code returned to any waiting threads.
///
/// \return Returns XOS_OK on success, else error code.
///
/// NOTE: If the thread is blocked waiting for something, the wait is aborted
/// and the thread is made ready.
/// NOTE: The thread is not guaranteed to have exited when this call returns.
/// It will be made ready and set up for exit processing, but when the exit
/// processing will actually happen depends on the state of the system and
/// the priority of the thread being aborted.
///
//-----------------------------------------------------------------------------
int32_t
xos_thread_abort(XosThread * thread, int32_t exitcode);
//-----------------------------------------------------------------------------
///
/// Exit the current thread. The exit handler (if any) will be run before the
/// thread terminates.
///
/// \param exitcode Exit code to be returned to any waiting threads.
///
/// \return This function does not return.
///
/// NOTE: This is automatically called if the thread returns from its entry
/// function. The entry function's return value will be passed as the exit
/// code.
///
//-----------------------------------------------------------------------------
void
xos_thread_exit(int32_t exitcode);
//-----------------------------------------------------------------------------
///
/// Wait until the specified thread exits and get its exit code. If the thread
/// has exited already, an error will be returned.
///
/// \param thread The thread to wait for. Cannot be "self", i.e.
/// one cannot wait on one's own exit.
///
/// \param p_exitcode If not null, the exit code will be returned here.
///
/// \return Returns XOS_OK on sucess, else error code.
///
//-----------------------------------------------------------------------------
int32_t
xos_thread_join(XosThread * thread, int32_t * p_exitcode);
//-----------------------------------------------------------------------------
///
/// Yield the CPU to the next thread in line. The calling thread remains ready
/// and is placed at the tail of the ready queue at its current priority level.
/// If there are no threads at the same priority level that are ready to run,
/// then this call will return immediately.
///
/// \return Returns nothing.
///
//-----------------------------------------------------------------------------
void
xos_thread_yield();
//-----------------------------------------------------------------------------
///
/// Suspend the specified thread. The thread will remain suspended until
/// xos_thread_resume() has been called on it. If the thread is already blocked
/// on some other condition, then this function will return an error.
///
/// \param thread Handle of thread being suspended. A thread can
/// use the special handle XOS_THREAD_SELF to suspend
/// itself.
///
/// \return Returns XOS_OK on success, else error code.
///
//-----------------------------------------------------------------------------
int32_t
xos_thread_suspend(XosThread * thread);
//-----------------------------------------------------------------------------
///
/// Resume a suspended thread. If the thread is not suspended or is blocked on
/// some other condition then this function will do nothing. Otherwise, it will
/// be made ready, and this can cause an immediate context switch if the thread
/// is at a higher priority than the calling thread.
///
/// \param thread Handle of thread being resumed.
///
/// \return Returns XOS_OK on success, else error code.
///
//-----------------------------------------------------------------------------
int32_t
xos_thread_resume(XosThread * thread);
//-----------------------------------------------------------------------------
///
/// Get the priority of the specified thread. This returns the priority of the
/// queried thread at this instant, however this can change at any time due to
/// other activity in the system.
///
/// \param thread Handle of thread being queried. A thread can use
/// the special handle XOS_THREAD_SELF to query itself.
///
/// \return Returns the thread's current priority, or -1 if the thread handle
/// is not valid.
///
//-----------------------------------------------------------------------------
static inline int32_t
xos_thread_get_priority(XosThread * thread)
{
XOS_ASSERT(thread);
return thread ? thread->priority : -1;
}
//-----------------------------------------------------------------------------
///
/// Set the priority of the specified thread. The thread must exist.
///
/// \param thread Handle of thread being affected. A thread can
/// use the special handle XOS_THREAD_SELF to specify
/// itself.
///
/// \param priority The new priority level to be set.
///
/// \return Returns XOS_OK on success, else error code.
///
/// NOTE: Calling this function can result in a scheduler activation, and the
/// caller may be suspended as a result.
///
//-----------------------------------------------------------------------------
int32_t
xos_thread_set_priority(XosThread * thread, int32_t priority);
//-----------------------------------------------------------------------------
///
/// Return the name of the specified thread.
///
/// \param thread Handle of thread being queried. A thread can use
/// the special handle XOS_THREAD_SELF to specify
/// itself.
///
/// \return Returns a pointer to the name string if available, else NULL.
///
//-----------------------------------------------------------------------------
static inline const char *
xos_thread_get_name(XosThread * thread)
{
XOS_ASSERT(thread);
return thread ? thread->name : 0;
}
//-----------------------------------------------------------------------------
///
/// Set the name of the specified thread.
///
/// \param thread Handle of thread whose name is to be set. A thread
/// can use the special handle XOS_THREAD_SELF to specify
/// itself.
///
/// \param name Pointer to the new name string. The string is not
/// copied, only the pointer is saved. So the string
/// must be persistent for the life of the thread.
///
/// \return Returns XOS_OK on success, else error code.
///
//-----------------------------------------------------------------------------
static inline int32_t
xos_thread_set_name(XosThread * thread, const char * name)
{
XOS_ASSERT(thread);
if (thread != XOS_NULL) {
thread->name = name;
return XOS_OK;
}
return XOS_ERR_INVALID_PARAMETER;
}
//-----------------------------------------------------------------------------
///
/// Set an exit handler for the specified thread. The exit handler is run when
/// the thread terminates, either by calling xos_thread_exit() or by returning
/// from its entry function. It will also be called if the thread is being
/// terminated due to e.g. an unhandled exception.
///
/// The handler must be a function defined as e.g.:
///
/// int32_t exit_handler(int32_t exitcode);
///
/// The exit handler runs in the context of the exiting thread, and can call
/// system services. It is provided with a single parameter which is the
/// thread's exit code (the exit code may be set to an error code if the
/// thread is being terminated due to an error or exception). The handler
/// must return a value which will be set as the thread's exit code.
///
/// \param thread Handle of the thread for which the handler is
/// to be installed. A thread can use the special
/// handle XOS_THREAD_SELF to specify itself.
///
/// \param func Pointer to exit handler function. To clear an
/// existing handler, pass NULL as the pointer.
///
/// \return Returns XOS_OK on success, else error code.
///
//-----------------------------------------------------------------------------
int32_t
xos_thread_set_exit_handler(XosThread * thread, XosThdExitFunc * func);
//-----------------------------------------------------------------------------
///
/// Return the ID (handle) of the current thread.
///
/// \return Returns the handle of the current thread. This handle can be
/// used in all XOS system calls.
///
/// NOTE: If called from interrupt context, returns the handle of the thread
/// that was preempted.
///
//-----------------------------------------------------------------------------
static inline XosThread *
xos_thread_id()
{
return xos_curr_threadptr;
}
//-----------------------------------------------------------------------------
///
/// Return the coprocessor mask for the specified thread.
///
/// \param thread Handle of thread being queried.
///
/// \return Returns the mask for the specified thread if available, else 0.
///
//-----------------------------------------------------------------------------
static inline uint16_t
xos_thread_cp_mask(XosThread * thread)
{
XOS_ASSERT(thread);
return thread ? thread->cp_mask : 0;
}
//-----------------------------------------------------------------------------
///
/// Return the wake value for the specified thread.
///
/// \return thread Handle of thread being queried.
///
/// \return Returns The last set wake value. There is no way to detect what
/// action set the wake value and when.
///
//-----------------------------------------------------------------------------
static inline int32_t
xos_thread_get_wake_value(XosThread * thread)
{
XOS_ASSERT(thread);
return thread ? thread->wake_value : 0;
}
//-----------------------------------------------------------------------------
///
/// Return the current value of the event bits for the current thread.
/// This function takes no parameters.
///
/// \return Returns the current value of the event bits. The event bits
/// are set when the thread is woken from an event wait. They will
/// not change while the thread is running. There is no way to
/// determine when the event bits were last updated.
///
//-----------------------------------------------------------------------------
static inline uint32_t
xos_thread_get_event_bits(void)
{
XosThread * thread = xos_thread_id();
return thread ? thread->event_bits : 0;
}
//-----------------------------------------------------------------------------
///
/// Enum values for thread state.
///
//-----------------------------------------------------------------------------
typedef enum xos_thread_state_t {
XOS_THREAD_STATE_INVALID = 0, ///< Invalid thread
XOS_THREAD_STATE_BLOCKED, ///< Thread is blocked
XOS_THREAD_STATE_READY, ///< Thread is ready to run
XOS_THREAD_STATE_RUNNING, ///< Thread is running
XOS_THREAD_STATE_EXITED, ///< Thread has exited
} xos_thread_state_t;
//-----------------------------------------------------------------------------
///
/// Return the state of the specified thread.
///
/// \param thread Handle of thread being queried.
///
/// \return Returns one of the following values:
/// - XOS_THREAD_STATE_RUNNING -- The thread is currently running.
/// - XOS_THREAD_STATE_READY -- The thread is ready to run.
/// - XOS_THREAD_STATE_BLOCKED -- The thread is blocked on something.
/// - XOS_THREAD_STATE_INVALID -- The thread handle is invalid.
/// - XOS_THREAD_STATE_EXITED -- The thread has exited.
///
//-----------------------------------------------------------------------------
xos_thread_state_t
xos_thread_get_state(XosThread * thread);
//-----------------------------------------------------------------------------
///
/// Disable thread preemption. Prevents context switching to another thread.
/// However, interrupt handlers will still continue to be run. Multiple calls
/// will nest, and the same number of calls to xos_preemption_enable() will be
/// required to re-enable preemption. If the calling thread yields the CPU or
/// exits without enabling preemption, it will cause a system halt.
/// If the calling thread encounters a fatal error, preemption will be enabled
/// during fatal error handling.
///
/// \return Returns the new value of preemption disable flag after this call.
///
/// NOTE: Cannot be called from interrupt context.
///
//-----------------------------------------------------------------------------
uint32_t
xos_preemption_disable(void);
//-----------------------------------------------------------------------------
///
/// Enable thread preemption. Has no effect if preemption was already enabled.
/// Otherwise, it decrements the value of the preemption disable flag and if
/// the value goes to zero, enables preemption.
///
/// \return Returns the new value of preemption disable flag after this call.
///
/// NOTE: If scheduling gets enabled, it may cause an immediate context switch
/// if higher priority threads are ready.
///
//-----------------------------------------------------------------------------
uint32_t
xos_preemption_enable(void);
//-----------------------------------------------------------------------------
///
/// Initialize XOS thread support and start scheduler.
///
/// Must be called from main() before calling any other thread function.
/// This function initializes thread support, creates the idle thread, and
/// starts the scheduler. It does not return to its caller. This means that
/// at least one user thread must be created before calling xos_start().
/// Otherwise, the scheduler will run the idle thread since it will be the
/// only thread in the system, and no other thread can be created.
///
/// NOTE: This function does not initialize timer/tick support. For timer
/// services to be available xos_start_system_timer() must be called.
///
/// NOTE: xos_start() and xos_start_main() are exclusive, both cannot be
/// called within the same application.
///
/// \param flags Currently unused (pass 0).
///
/// \return Does not return.
///
//-----------------------------------------------------------------------------
void
xos_start(uint32_t flags);
//-----------------------------------------------------------------------------
///
/// Initialize XOS thread support and create init (main) thread.
///
/// Must be called from main() before calling any other thread function.
/// This function converts the caller into the 'main' or 'init' thread, and
/// returns to the caller after completing initialization.
///
/// NOTE: This function does not initialize timer/tick support. For timer
/// services to be available xos_start_system_timer() must be called.
///
/// NOTE: xos_start_main() and xos_start() are exclusive, both cannot be
/// called within the same application.
///
/// \param name Name of main thread (see xos_thread_create()).
///
/// \param priority Initial priority of main thread.
///
/// \param flags Currently unused (pass 0).
///
/// \return Returns nothing.
///
//-----------------------------------------------------------------------------
void
xos_start_main(const char * name, int8_t priority, uint32_t flags);
//-----------------------------------------------------------------------------
///
/// Per-thread stats structure.
/// Note that the CPU use % is approximate, both because of cycle counting
/// and because of integer division. So all the threads' CPU % will not add
/// up to exactly 100%.
///
//-----------------------------------------------------------------------------
typedef struct XosThreadStats {
XosThread * thread; ///< Thread handle (or pseudo-handle)
uint32_t cpu_pct; ///< CPU use % for this thread
uint32_t normal_switches; ///< Number of non-preemptive switches.
uint32_t preempt_switches; ///< Number of preemptive switches.
uint64_t cycle_count; ///< Number of cycles consumed.
} XosThreadStats;
//-----------------------------------------------------------------------------
// Thread pseudo-handles.
//-----------------------------------------------------------------------------
#define XOS_THD_STATS_IDLE ((XosThread *) 1)
#define XOS_THD_STATS_INTR ((XosThread *) 2)
//-----------------------------------------------------------------------------
///
/// Get the thread statistics for the specified thread. Statistics are only
/// available if XOS_OPT_STATS has been enabled. Otherwise, the function
/// will return XOS_OK, but the structure contents will be undefined.
///
/// \param thread Handle of thread being queried. The following
/// special pseudo-handles can be used:
/// - XOS_THD_STATS_IDLE -- stats for idle thread
/// - XOS_THD_STATS_INTR -- stats for interrupt processing
///
/// \param stats Pointer to XosThreadStats struct to be filled in.
///
/// \return Returns XOS_OK on success, else error code.
///
/// NOTE: Can be called from interrupt context.
/// NOTE: This call will not fill in the "thread" and "cpu_pct" fields in the
/// "stats" structure. The thread handle is already known, and calculating the
/// CPU loading can take quite a bit of time so is not done here.
///
//-----------------------------------------------------------------------------
int32_t
xos_thread_get_stats(XosThread * thread, XosThreadStats * stats);
//-----------------------------------------------------------------------------
///
/// Get CPU loading statistics for the system. This function computes the CPU
/// percentage use for all threads in the system (including the idle thread and
/// the 'interrupt thread' (interrupt context). It also returns the cycle count
/// and number of context switches for each thread.
/// Statistics are only available if XOS_OPT_STATS has been enabled.
/// Otherwise, the function will return XOS_OK, but the structure contents will
/// be undefined.
///
/// IMPORTANT: The entry for interrupt context does not contain a real thread
/// handle. It uses the pseudo-handle XOS_THD_STATS_INTR to indicate that this
/// entry reports interrupt statistics. This pseudo-handle cannot be used for
/// any other thread operations or queries.
///
/// NOTE: This function disables interrupts while traversing the thread list.
/// It does not leave interrupts disabled during the computations, as that can
/// take a fair amount of time.
///
/// \param stats Pointer to an array of XosThreadStats structures.
/// The array must be large enough to accommodate all
/// threads in the system.
///
/// \param size The number of elements available in the array. If
/// this is smaller than the number of threads plus one
/// (for the interrupt context) then XOS_ERR_INVALID_PARAMETER
/// will be returned and '*size' will be set to the
/// minimum number of elements required. On a successful
/// return, '*size' is set to the number of elements
/// actually filled in.
///
/// \param reset If nonzero, then thread stats counters are reset
/// after reading. This is useful if you want to track
/// the stats so as to get a better idea of current
/// system loading. E.g. calling this function once a
/// second with 'reset' nonzero will provide CPU load
/// information for the last second on each call.
///
/// \return Returns XOS_OK on success, else error code. In particular,
/// XOS_ERR_INVALID_PARAMETER will be returned if the output buffer
/// is too small.
///
//-----------------------------------------------------------------------------
int32_t
xos_get_cpu_load(XosThreadStats * stats, int32_t * size, int32_t reset);
#ifdef _XOS_INCLUDE_INTERNAL_
// Signature of valid thread object
#define XOS_THREAD_SIG 0x54485244
// Extern functions
void
xos_init(void);
bool
xos_init_done(void);
bool
xos_started(void);
int32_t
xos_schedule(XosThread * curr_thread);
void
xos_q_remove(XosThreadQueue * queue, XosThread * thread);
XosThread *
xos_q_pop(XosThreadQueue * queue);
int32_t
xos_wake_queue(XosThreadQueue * queue, const char * expected_cause, int32_t wake_value);
// Well known block causes
extern const char * const xos_blkon_idle; // (for idle thread only)
extern const char * const xos_blkon_suspend;
extern const char * const xos_blkon_delay;
extern const char * const xos_blkon_exited;
extern const char * const xos_blkon_join;
extern const char * const xos_blkon_event;
extern const char * const xos_blkon_condition;
extern const char * const xos_blkon_mutex;
extern const char * const xos_blkon_sem;
extern const char * const xos_blkon_msgq;
//-----------------------------------------------------------------------------
// Blocks the current active thread.
//
// Currently, this can be called from an interrupt handler to block the thread
// that was interrupted. Note that in interrupt context the current thread can
// already be in the blocked state, due to a previous call to this function.
// Can be called with interrupts enabled.
//
// block_cause Reason for blocking.
//
// block_queue Queue on to which this thread should be pushed once it
// is blocked. Can be NULL.
//
// must_schedule If nonzero, then forces a scheduling operation to pick
// the next thread to run, even if there are ready threads
// at the same priority level as the blocked thread.
//
// use_priority If nonzero, then the blocked thread will be queued in
// priority order in the specified block queue. If zero,
// the thread is queued in FIFO order. If no queue has
// been specified, this parameter is ignored.
//
// Returns: The value passed by xos_thread_wake().
//-----------------------------------------------------------------------------
int32_t
xos_block(const char * block_cause,
XosThreadQueue * block_queue,
int32_t must_schedule,
int32_t use_priority);
//-----------------------------------------------------------------------------
// Unblocks the specified blocked thread and puts it at the tail end of its
// ready queue. Schedules it if it is higher priority than the current thread.
// No effect if the thread is not blocked with the specified cause.
//
// thread The thread to wake up (make ready).
//
// expected_cause The expected block cause of the thread. Thread will be
// woken only if its block cause matches this cause, or if
// expected_cause is zero.
//
// wake_value The value to be passed to the woken thread as a return
// value from xos_thread_block().
//
// Returns: nothing.
//
// The target thread can be woken at a different priority by changing its
// priority while the thread is blocked.
// Can be called with interrupts enabled. Can be called in interrupt context.
//-----------------------------------------------------------------------------
void
xos_thread_wake(XosThread * thread, const char * expected_cause, int32_t wakevalue);
//-----------------------------------------------------------------------------
// Function to init C library per-thread and reentrancy support.
//-----------------------------------------------------------------------------
#if XOS_OPT_THREAD_SAFE_CLIB
void
xos_clib_init(void);
void
xos_clib_thread_init(XosThread * thread);
void
xos_clib_thread_cleanup(XosThread * thread);
#endif
#endif
#ifdef __cplusplus
}
#endif
#endif // __XOS_THREAD_H__