xos_thread.h

/** @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__