/** @file */
// xos.h - XOS API interface and data structures visible to user code.
// 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.
#ifndef __XOS_H__
#define __XOS_H__
#ifdef __cplusplus
extern "C" {
#endif
#include "xos_types.h"
#include <xtensa/config/core.h>
#if XCHAL_HAVE_INTERRUPTS
#include <xtensa/tie/xt_core.h>
#include <xtensa/tie/xt_interrupt.h>
#endif
#include "xos_common.h"
#include "xos_errors.h"
#include "xos_regaccess.h"
//-----------------------------------------------------------------------------
// Convert x into a literal string.
//-----------------------------------------------------------------------------
#define _XOS_STR(x) __XOS_STR(x)
#define __XOS_STR(x) #x
//-----------------------------------------------------------------------------
// XOS version.
//-----------------------------------------------------------------------------
#define XOS_VERSION_MAJOR 1
#define XOS_VERSION_MINOR 10
#define XOS_VERSION_STRING "1.10" ///< XOS version string.
//-----------------------------------------------------------------------------
// Runtime error handling.
//-----------------------------------------------------------------------------
//-----------------------------------------------------------------------------
///
/// Reports a fatal error and halts XOS operation, i.e. halts the system. This
/// function will call a user-registered error handler (if one has been set)
/// and then halt the system. The user handler may do system-specific things
/// such as record the error reason in nonvolatile memory etc.
///
/// \param errcode Error code. May be any user defined value < 0.
/// Values >=0 are reserved for use by the system.
///
/// \param errmsg Optional text string describing the error.
///
/// \return This function does not return.
///
//-----------------------------------------------------------------------------
void
xos_fatal_error(int32_t errcode, const char * errmsg);
#if XOS_DEBUG
// Do not call directly.
void
xos_assert(const char * file, int32_t line);
//-----------------------------------------------------------------------------
///
/// Check condition and fail if condition expression is false.
/// In debug builds, an assertion failure will cause a fatal error to be
/// reported. In non-debug builds, assertions are compiled out.
///
/// NOTE: Remember that any code in XOS_ASSERT() statements gets compiled out
/// for non-debug builds.
///
//-----------------------------------------------------------------------------
#define XOS_ASSERT(expr) if ((expr) == 0) xos_assert(__FILE__, __LINE__)
#else
#define XOS_ASSERT(expr)
#endif
//-----------------------------------------------------------------------------
///
/// Interrupt handler function pointer type.
///
//-----------------------------------------------------------------------------
typedef void (XosIntFunc)(void * arg);
//-----------------------------------------------------------------------------
///
/// Print handler function pointer type.
///
//-----------------------------------------------------------------------------
typedef int32_t (XosPrintFunc)(void * arg, const char * fmt, ...);
//-----------------------------------------------------------------------------
///
/// Fatal error handler function pointer type.
///
//-----------------------------------------------------------------------------
typedef void (XosFatalErrFunc)(int32_t errcode, const char * errmsg);
//-----------------------------------------------------------------------------
///
/// Exception handler function pointer type.
///
//-----------------------------------------------------------------------------
typedef void (XosExcHandlerFunc)(XosExcFrame * frame);
//-----------------------------------------------------------------------------
///
/// Install a user defined exception handler for the specified exception type.
/// This will override the default XOS exception handler. The handler is a C
/// function that is passed one parameter -- a pointer to the exception frame.
/// The exception frame is allocated on the stack of the thread that caused the
/// exception, and contains saved state and exception information. For details
/// of the exception frame see the structure XosExcFrame.
///
/// \param exc Exception type (number) to override. The exception
/// numbers are enumerated in <xtensa/corebits.h>.
///
/// \param handler Pointer to handler function to be installed.
/// To revert to the default handler, pass NULL.
///
/// \return Returns a pointer to previous handler installed, if any.
///
//-----------------------------------------------------------------------------
XosExcHandlerFunc *
xos_register_exception_handler(int32_t exc, XosExcHandlerFunc * handler);
//-----------------------------------------------------------------------------
///
/// Install a user defined fatal error handler. This function will be called if
/// a fatal error is reported either by user code or by XOS itself. It will be
/// passed the same arguments that are passed to xos_fatal_error().
///
/// The handler need not return. It should make minimal assumptions about the
/// state of the system. In particular, it should not assume that further XOS
/// system calls will succeed.
///
/// \param handler Pointer to handler function to be installed.
///
/// \return Returns a pointer to previous handler installed, if any.
///
//-----------------------------------------------------------------------------
XosFatalErrFunc *
xos_register_fatal_error_handler(XosFatalErrFunc * handler);
#ifdef _XOS_INCLUDE_INTERNAL_
# include "xos_internal.h"
#endif
#include "xos_thread.h"
#include "xos_timer.h"
#include "xos_cond.h"
#include "xos_event.h"
#include "xos_mutex.h"
#include "xos_msgq.h"
#include "xos_semaphore.h"
#include "xos_stopwatch.h"
//-----------------------------------------------------------------------------
///
/// Register a handler function to call when interrupt "num" occurs.
///
/// For level-triggered and timer interrupts, the handler function will have
/// to clear the source of the interrupt before returning, to avoid infinitely
/// retaking the interrupt. Edge-triggered and software interrupts are
/// automatically cleared by the OS interrupt dispatcher (see xos_handlers.S).
///
/// \param num Xtensa internal interrupt number (0..31). To
/// refer to a specific external interrupt number
/// (BInterrupt pin), use HAL macro XCHAL_EXTINTx_NUM
/// where 'x' is the external number.
///
/// \param handler Pointer to handler function.
///
/// \param arg Argument passed to handler.
///
/// \return Returns XOS_OK if successful, else error code.
///
//-----------------------------------------------------------------------------
int32_t
xos_register_interrupt_handler(int32_t num, XosIntFunc * handler, void * arg);
//-----------------------------------------------------------------------------
///
/// Unregister a handler function for interrupt "num". If no handler was
/// installed, this function will have no effect.
///
/// \param num Xtensa internal interrupt number (0..31). To
/// refer to a specific external interrupt number
/// (BInterrupt pin), use HAL macro XCHAL_EXTINTx_NUM
/// where 'x' is the external number.
///
/// \return Returns XOS_OK if successful, else error code.
///
//-----------------------------------------------------------------------------
int32_t
xos_unregister_interrupt_handler(int32_t num);
//-----------------------------------------------------------------------------
///
/// Register a high priority interrupt handler for interrupt level "level".
///
/// Unlike low and medium priority interrupt handlers, high priority handlers
/// are not installed for a specific interrupt number, but for an interrupt
/// level. The level must be above XCHAL_EXCM_LEVEL. The handler function must
/// be written in assembly since C handlers are not supported for levels above
/// XCHAL_EXCM_LEVEL. The handler function must preserve all registers except
/// a0, and must return to the dispatcher via a "ret" instruction, not "rfi".
///
/// NOTE: This method of dispatch takes a few cycles of overhead. If you wish
/// to save even these cycles, then you can define your own dispatch function
/// to override the built-in dispatcher. See xos_handlers.S for more details.
///
/// \param level The interrupt level to be handled.
///
/// \param handler Pointer to handler function.
///
/// \return Returns XOS_OK if successful, else error code.
///
//-----------------------------------------------------------------------------
int32_t
xos_register_hp_interrupt_handler(int32_t level, void * handler);
//-----------------------------------------------------------------------------
///
/// Enable a specific interrupt, by interrupt number.
/// The state (enabled vs. disabled) of individual interrupts is global, i.e.
/// not associated with any specific thread. Depending on system options and
/// implementation, this state may be stored in one of two ways:
/// - directly in the INTENABLE register, or
/// - in a global variable (this is generally the case when INTENABLE is used
/// not just to control what interrupts are enabled globally, but also for
/// software interrupt prioritization within an interrupt level, effectively
/// providing finer grained levels; in this case XOS takes care to update
/// INTENABLE whenever either the global enabled-state variable or the
/// per-thread fine-grained-level variable change).
/// Thus it is best to never access the INTENABLE register directly.
///
/// To modify thread-specific interrupt priority level, use one of:
/// - xos_set_int_pri_level()
/// - xos_restore_int_pri_level()
/// - xos_disable_interrupts()
/// - xos_restore_interrupts()
///
/// NOTE: To refer to a specific external interrupt number (BInterrupt pin),
/// use HAL macro XCHAL_EXTINTx_NUM where 'x' is the external interrupt
/// number. For example, to enable external interrupt 3 (BInterrupt[3]),
/// you can use:
///
/// xos_interrupt_enable( XCHAL_EXTINT3_NUM );
///
/// \param intnum Interrupt number to enable. Must range between 0-31.
///
/// \return Returns nothing.
///
//-----------------------------------------------------------------------------
void
xos_interrupt_enable(uint32_t intnum);
//-----------------------------------------------------------------------------
///
/// Disable a specific individual interrupt, by interrupt number.
///
/// This is the counterpart to xos_interrupt_enable(). See the description
/// of xos_interrupt_enable() for further comments and notes.
///
/// \param intnum Interrupt number to disable. Must range between 0-31.
///
/// \return Returns nothing.
///
//-----------------------------------------------------------------------------
void
xos_interrupt_disable(uint32_t intnum);
//-----------------------------------------------------------------------------
///
/// Get the CPU's current interrupt priority level. Interrupts at or below this
/// priority level are blocked.
///
/// \return Returns the current IPL, ranging from 0 to XCHAL_NUM_INTLEVELS.
///
//-----------------------------------------------------------------------------
static inline uint32_t
xos_get_int_pri_level(void)
{
#if XCHAL_HAVE_INTERRUPTS
return XT_RSR_PS() & 0xF;
#else
return 0;
#endif
}
//-----------------------------------------------------------------------------
///
/// Set the CPU's interrupt priority level to the specified level, but only if
/// the current IPL is below the one requested. This function will never cause
/// the interrupt priority level to be lowered from the current level.
/// Call this function to block interrupts at or below the specified priority
/// level.
///
/// When setting the IPL temporarily (such as in a critical section), call
/// xos_set_int_pri_level(), execute the critical code section, and then call
/// xos_restore_int_pri_level().
///
/// The interrupt priority level is part of the thread context, so it is saved
/// and restored across context switches. To enable and disable individual
/// interrupts globally, use the functions xos_interrupt_enable() and
/// xos_interrupt_disable() instead.
///
/// NOTE: It is usually not required to disable interrupts at a level higher
/// than that of the highest priority interrupt that interacts with the OS
/// (i.e. calls into XOS such that threads may be woken / blocked /
/// reprioritized / switched, or otherwise access XOS data structures).
/// In XOS, that maximum level is XOS_MAX_OS_INTLEVEL, which defaults to
/// XCHAL_EXCM_LEVEL. This may be modified by editing xos_params.h and
/// rebuilding XOS.
///
/// \param level The new interrupt priority level (IPL).
///
/// \return Returns a value that can be used to restore the previous
/// priority level by calling xos_restore_int_pri_level(). This
/// value should be treated as opaque by application code, and
/// should be passed unchanged to the restore function.
///
//-----------------------------------------------------------------------------
__attribute__((always_inline))
static inline uint32_t
xos_set_int_pri_level(uint32_t level)
{
#if XCHAL_HAVE_INTERRUPTS
#pragma no_reorder
uint32_t ps = XT_RSR_PS();
if (level > (ps & 0xF)) {
level = (ps & ~0xF) | level;
XT_WSR_PS(level);
XT_RSYNC();
}
return ps;
#else
return 0;
#endif
}
//-----------------------------------------------------------------------------
///
/// Restores the CPU to a previously saved interrupt priority level. This level
/// must have been obtained by calling xos_set_int_pri_level().
///
/// \param oldval Return value from xos_set_int_pri_level().
///
/// \return Returns nothing.
///
//-----------------------------------------------------------------------------
__attribute__((always_inline))
static inline void
xos_restore_int_pri_level(const uint32_t oldval)
{
#if XCHAL_HAVE_INTERRUPTS
#pragma no_reorder
XT_WSR_PS(oldval);
XT_RSYNC();
#else
// Nothing
#endif
}
//-----------------------------------------------------------------------------
///
/// Disable all interrupts that can interact directly with the OS. This is a
/// convenience function, shorthand for setting the IPL to XOS_MAX_OS_INTLEVEL.
///
/// Returns: A value that can be used to restore the previous priority level
/// by calling xos_restore_interrupts(). This value should be treated as
/// opaque by application code, and should be passed unchanged to the restore
/// function.
///
//-----------------------------------------------------------------------------
static inline uint32_t
xos_disable_interrupts(void)
{
return xos_set_int_pri_level(XOS_MAX_OS_INTLEVEL);
}
//-----------------------------------------------------------------------------
///
/// Restore the CPU's previously saved interrupt status. This is a convenience
/// function, the counterpart to xos_disable_interrupts().
///
/// \return rval Return value from xos_disable_interrupts().
///
/// \return Returns nothing.
///
//-----------------------------------------------------------------------------
static inline void
xos_restore_interrupts(uint32_t rval)
{
xos_restore_int_pri_level(rval);
}
#ifdef _XOS_INCLUDE_INTERNAL_
//-----------------------------------------------------------------------------
// Enter an OS critical section, i.e. get exclusive access to OS critical
// state and data structures. Code that manipulates the state of OS objects
// or modifies internal OS state must call this function first, to ensure
// that it has exclusive access. On a single-core system, this is equivalent
// to blocking all interrupts that can interact directly with the OS, i.e.
// all interrupts at or below XOS_MAX_OS_INTLEVEL. In a multi-core system
// this is likely to be implemented differently to achieve the same effect.
//
// Returns: A value that is to be used to restore the state of the CPU when
// exiting the critical section. This must be treated as opaque and passed
// unmodified to xos_critical_exit().
//
// NOTE: This function is meant for use in OS code, not in applications.
//-----------------------------------------------------------------------------
__attribute__((always_inline))
static inline uint32_t
xos_critical_enter(void)
{
#if XCHAL_HAVE_INTERRUPTS
// This function cannot be called by high-level interrupt handlers,
// i.e. it can never be called with intlevel > XOS_MAX_OS_INTLEVEL.
// So, we do not need to check current intlevel because we will not
// ever be lowering it by setting it to XOS_MAX_OS_INTLEVEL.
// NOTE: sync after RSIL not needed.
return XT_RSIL(XOS_MAX_OS_INTLEVEL);
#else
return 0;
#endif
}
//-----------------------------------------------------------------------------
// Exit an OS critical section and restore CPU state. See the documentation
// for xos_critical_enter().
//
// cflags Return value from xos_critical_enter().
// Must be treated as an opaque value.
//
// Returns: Nothing.
//
// NOTE: This function is meant for use in OS code, not in applications.
//-----------------------------------------------------------------------------
__attribute__((always_inline))
static inline void
xos_critical_exit(uint32_t cflags)
{
xos_restore_int_pri_level(cflags);
}
#endif // _XOS_INCLUDE_INTERNAL_
// This file uses things defined above
#include "xos_syslog.h"
// Misc
//-----------------------------------------------------------------------------
// Helper function to list all threads in system. Useful for debug.
//-----------------------------------------------------------------------------
void
xos_display_threads(void * arg, XosPrintFunc * print_fn);
#ifdef __cplusplus
}
#endif
#endif // __XOS_H__