esp-idf/components/esp32/include/xtensa/xmp-library.h

/* Customer ID=11656; Build=0x5f626; Copyright (c) 2008-2009 by Tensilica Inc.  ALL RIGHTS RESERVED.
   These coded instructions, statements, and computer programs are the
   copyrighted works and confidential proprietary information of Tensilica Inc.
   They may not be modified, copied, reproduced, distributed, or disclosed to
   third parties in any manner, medium, or form, in whole or in part, without
   the prior written consent of Tensilica Inc.  */

#ifndef _XMP_LIBRARY_H
#define _XMP_LIBRARY_H

#ifdef __cplusplus
extern "C" {
#endif

#include <xtensa/config/core-isa.h>
#include <xtensa/config/core.h>
#include <xtensa/tie/xt_core.h>
#if XCHAL_HAVE_RELEASE_SYNC
#include <xtensa/tie/xt_sync.h>
#endif
#if XCHAL_HAVE_EXTERN_REGS
#include <xtensa/xtensa-xer.h>
#endif
#include <stdlib.h>
#include <stdio.h>

#include "xtensa/system/mpsystem.h"

/* 
   W A R N I N G:

   xmp library clients should treat all data structures in this file
   as opaque.  They are only public to enable users to declare them
   statically.
*/


/* -------------------------------------------------------------------------
   When using XMP on cache-incoherent systems, these macros are helpful
   to ensure that you are not reading stale data, and to ensure that
   the data you write makes it all the way back to main memory.
 */

#if !XCHAL_DCACHE_IS_COHERENT
#define XMP_WRITE_BACK_ELEMENT(x) xthal_dcache_region_writeback((void *)x, sizeof(*x))
#define XMP_INVALIDATE_ELEMENT(x) xthal_dcache_region_invalidate((void *)x, sizeof(*x))
#define XMP_WRITE_BACK_INVALIDATE_ELEMENT(x) xthal_dcache_region_writeback_inv((void *)x, sizeof(*x))
#define XMP_WRITE_BACK_ARRAY(x) xthal_dcache_region_writeback((void *)x, sizeof(x))
#define XMP_INVALIDATE_ARRAY(x) xthal_dcache_region_invalidate((void *)x, sizeof(x))
#define XMP_WRITE_BACK_INVALIDATE_ARRAY(x) xthal_dcache_region_writeback_inv((void *)x, sizeof(x))
#define XMP_WRITE_BACK_ARRAY_ELEMENTS(x, num_elements) xthal_dcache_region_writeback((void *)x, sizeof(*x) * num_elements)
#define XMP_INVALIDATE_ARRAY_ELEMENTS(x, num_elements) xthal_dcache_region_invalidate((void *)x, sizeof(*x) * num_elements)
#define XMP_WRITE_BACK_INVALIDATE_ARRAY_ELEMENTS(x, num_elements) xthal_dcache_region_writeback_inv((void *)x, sizeof(*x) * num_elements)
#else 
#define XMP_WRITE_BACK_ELEMENT(x)
#define XMP_INVALIDATE_ELEMENT(x)
#define XMP_WRITE_BACK_INVALIDATE_ELEMENT(x)
#define XMP_WRITE_BACK_ARRAY(x)
#define XMP_INVALIDATE_ARRAY(x)
#define XMP_WRITE_BACK_INVALIDATE_ARRAY(x)
#define XMP_WRITE_BACK_ARRAY_ELEMENTS(x, num_elements)
#define XMP_INVALIDATE_ARRAY_ELEMENTS(x, num_elements)
#define XMP_WRITE_BACK_INVALIDATE_ARRAY_ELEMENTS(x, num_elements)
#endif

/* -------------------------------------------------------------------------
   Initialization, error codes, constants and house-keeping

   Every core should call xmp_init with the number of cores in the
   system.

   xmp_init should be called before you use any global synchronization
   primitive or shared data. 

   Further, before you use a dynamically allocated synchronization
   primitives, you need to both initialize it by calling the
   xmp_*_init function, and you need to have called xmp_init, which
   sets up interrupt handlers and interrupt routing.

   The second parameter sets the interprocessor interrupt
   routing. Passing zero instructs the library to use the default
   routing, which will be suitable for most users.
   
*/
   
extern void xmp_init (int num_cores, unsigned int interrupt_routing);


/* If you want finer-grained control than that provided by xmp_init,
   you can the functions below individually--however, this is more
   inconvenient and requires greater understanding of the library's
   internals.  Don't use them directly unless you have a good reason.
*/

extern void xmp_unpack_shared (void);
extern void xmp_route_interrupts (unsigned int routing);

#if XCHAL_HAVE_MP_INTERRUPTS
extern void xmp_enable_ipi_interrupts (void);

/* Turn off certain things enabled by xmp_init  */
extern void xmp_disable_ipi_interrupts (void);
#endif

extern void xmp_end (void);

/* Only valid after xmp_init.  */
extern int xmp_num_cores (void);

/* How many cycles should a core wait before rechecking a
   synchronization variable?  Higher values will reduce memory
   transactions, but will also result in higher latency in returning
   from synchronization.
*/
extern void xmp_spin_wait_set_cycles (unsigned int limit);

/* If you would prefer to provide your own spin wait function,
   to go to sleep, etc.  Declare a function of this type, then call
   this function.  */
typedef void (*xmp_spin_wait_function_t)(void);
extern void xmp_spin_wait_set_function (xmp_spin_wait_function_t func);
extern void xmp_spin(void);

#define XMP_NO_OWNER        0x07
#define XMP_MUTEX_DESTROYED 0xFE
#define XMP_ERROR_FATAL     0xFD

#define XMP_MAX_CORES       0x4


static inline unsigned int xmp_prid (void) 
{
#if XCHAL_HAVE_PRID
  return XT_RSR_PRID() & 0xFF;
#else
  return 0;
#endif
}


/* -------------------------------------------------------------------------
   Tracing
   
   A core must set a trace_file if it wants any synchronization
   tracing to occur.  Sharing file descriptors among cores is very
   messy, so don't do it.  This, unfortunately, means that two cores
   contending for a mutex are not able to trace to the same file.

   Any object (except the atomic integer) can have tracing off or on.   
*/

extern void xmp_set_trace_file (FILE * file);
extern void xmp_trace (const char * fmt, ...);


/* -------------------------------------------------------------------------
   Memory Allocation Functions.

   These do what you would expect, only from shared memory instead of
   private memory.
*/

#if XCHAL_DCACHE_IS_COHERENT
extern void * xmp_malloc (size_t size);
extern void * xmp_calloc (size_t nmemb, size_t size);
extern void xmp_free (void * ptr);
#endif
extern void * xmp_sbrk(int size);

/* -------------------------------------------------------------------------
   xmp_atomic_int_t

   The most basic synchronization primitive in the xmp library.
   Atomic ints are sharable among processors, and even interrupt
   levels on the same processor. However, their semantics are fairly
   rudimentary.  All other primitives are based on these, therefore,
   changing this implementation affects all other primitives.

*/

typedef unsigned int xmp_atomic_int_t;

static inline xmp_atomic_int_t
xmp_coherent_l32ai(xmp_atomic_int_t * address)
{
  XMP_INVALIDATE_ELEMENT (address);
  return  XT_L32AI(address, 0);
}

static inline void
xmp_coherent_s32ri(xmp_atomic_int_t value, xmp_atomic_int_t  * address)
{
  XT_S32RI (value, address, 0);
  XMP_WRITE_BACK_ELEMENT (address);
}

#define XMP_ATOMIC_INT_INITIALIZER(value) (value)

/* xmp_atomic_int_init - Initialize an int prior to use

   Nonsynchronizing, Nonblocking 

   Usage: 
      value - initial value
      integer - points to an uninitialized integer

   On exit:
      initialized to given value

   Errors: none
*/

static inline void 
xmp_atomic_int_init (xmp_atomic_int_t * integer, int value)
{
  xmp_coherent_s32ri (value, integer);
}


/* xmp_atomic_int_value - Read the value 

   Nonsynchronizing, Nonblocking

   Usage: 
      integer - points to an int

   Returns:
      the value
*/

static inline int
xmp_atomic_int_value (xmp_atomic_int_t * integer)
{
  return xmp_coherent_l32ai (integer);
}


/* xmp_atomic_int_conditional_increment - Conditionally increment integer

   Synchronizing, nonblocking

   Usage: 
      integer - points to an initialized integer
      amount - how much to increment
      prev - believed value of the integer
                eg: prev = xmp_atomic_int_value (integer);
                    success = xmp_atomic_int_increment (integer, 1, prev);

   Returns: current value of integer - user should check if it matches
      the previous value of the integer. If it does, then the update
      was successful.

*/

#define USE_ASSEMBLY_IMPLEMENTATION 0

static inline int
xmp_atomic_int_conditional_increment (xmp_atomic_int_t * integer, int amount, int prev)
{
  int val;
  int saved;

#if USE_ASSEMBLY_IMPLEMENTATION
  /* %0 = prev
     %1 = saved
     %2 = atomic integer pointer
     %3 = amount
  */

  asm volatile ("wsr.scompare1 %0\n"
		"mov %1, %0\n"
		"add %0, %0, %3\n"
		"s32c1i %0, %2, 0\n"
		: "+&a" (prev), "+&a"(saved) : "a" (integer), "a" (amount));

  return prev;

#else

  XT_WSR_SCOMPARE1 (prev);
  val = prev + amount;
  saved = val;
  XT_S32C1I (val, integer, 0);

  return val;
#endif
}


/* xmp_atomic_int_increment - Increment integer

   Synchronizing, blocking

   Usage: 
      integer - points to an initialized integer
      amount - how much to increment

   Returns: new value of integer

*/

static inline int
xmp_atomic_int_increment (xmp_atomic_int_t * integer, int amount)
{
  int val;
  int saved;
#if USE_ASSEMBLY_IMPLEMENTATION
  /* %0 = val
     %1 = saved
     %2 = atomic integer pointer
     %3 = amount
  */
     
  asm volatile ("l32ai %0, %2, 0\n"
		"1:\n"
		"wsr.scompare1 %0\n"
		"mov %1, %0\n"
		"add %0, %0, %3\n"
		"s32c1i %0, %2, 0\n"
		"bne %0, %1, 1b\n" 
		: "+&a" (val), "+&a"(saved) : "a" (integer), "a" (amount));
#else
  /* Accurately naming "val" is tricky. Sometimes it will be what we
     want to be the new value, but sometimes it contains the value
     that is currently at the location.  */
  
  /* Load location's current value  */
  val = xmp_coherent_l32ai (integer);

  do {
    XT_WSR_SCOMPARE1 (val);
    saved = val;
    /* Change it to what we would like to store there--"new_val"  */
    val = val + amount;
    /* Possibly store new_val, but reload location's current value no
       matter what. */
    XT_S32C1I (val, integer, 0);
    if (val != saved)
      xmp_spin();
  } while (val != saved);

#endif
  return val + amount;
}


/* xmp_atomic_int_conditional_set - Set the value of an atomic integer

   Synchronizing, nonblocking

   Usage: 
      integer - points to an initialized integer
      from - believed value of the integer
                eg: prev = xmp_atomic_int_value (integer);
                    success = xmp_atomic_int_conditional_set (integer, 1, prev);
      to - new value

   Returns: current value of integer - user should check if it matches
      the previous value of the integer. If it does, then the update
      was successful.

*/

static inline int
xmp_atomic_int_conditional_set (xmp_atomic_int_t * integer, int from, int to)
{
  int val;

  /* Don't even try to update if the integer's value isn't what we
     think it should be.  This prevents acquiring this cache-line for
     writing and therefore prevents bus transactions when various
     cores contend.  */
  val = xmp_coherent_l32ai(integer);
  if (val == from) {
    XT_WSR_SCOMPARE1 (from);
    val = to;
    /* Possibly store to, but reload location's current value no
       matter what. */
    XT_S32C1I (val, integer, 0);
  }
  return val;
}


/* Macros to implement trivial spin locks.  These are very primitive, but
   can be useful when you don't need the higher-overhead synchronization.

   To use an xmp_atomic_int_t as a trivial spin lock, you should
   initialize it to zero first.
*/

#define XMP_SIMPLE_SPINLOCK_ACQUIRE(atomic_int_ptr)	\
  { while (xmp_atomic_int_conditional_set (atomic_int_ptr, 0, xmp_prid() + 1) != 0) \
      xmp_spin(); }
#define XMP_SIMPLE_SPINLOCK_RELEASE(atomic_int_ptr)	\
  { while (xmp_atomic_int_conditional_set (atomic_int_ptr, xmp_prid() + 1, 0) != xmp_prid() + 1) \
    xmp_spin(); }

#define XMP_SIMPLE_SPINLOCK_OWNER(atomic_int_ptr) (xmp_atomic_int_value(atomic_int_ptr) - 1)


/* -------------------------------------------------------------------------
   xmp_mutex_t - An even higher-level data structure to enforce
   mutual exclusion between cores.  A core which waits on a mutex might
   sleep with a waiti and be interrupted by an interrupt.

   Mutexes can be normal or recursive. For a normal mutex, a core
   attempting to acquire a mutex it already holds will result in
   deadlock. For a recursive mutex, a core will succeed in acquiring a
   mutex it already holds, and must release it as many times as it
   acquired it.

   Mutexes are not sharable between interrupt levels--because
   ownership is tracked by core, not thread.

   Like all xmp data structures, an object of type xmp_mutex_t
   should be treated by the programmer as opaque.  They are only
   public in this header file to allow them to be declared statically.

   For configurations with 16-byte cache lines, this has the most
   frequently used and changed data in the first line.

*/

#if XCHAL_DCACHE_IS_COHERENT
typedef struct xmp_mutex_t {
  xmp_atomic_int_t qlock;
  unsigned int qhead;
  unsigned int qtail;
  unsigned char queue[XMP_MAX_CORES];
  unsigned short held;

  unsigned char owner;
  unsigned char recursive : 1;
  unsigned char trace : 1;
  unsigned char system : 1;
  unsigned char unused : 5;
  const char * name;
} xmp_mutex_t __attribute__ ((aligned (XMP_MAX_DCACHE_LINESIZE)));


#define XMP_MUTEX_INITIALIZER(name)					\
  { 0, 0, -1, {XMP_NO_OWNER, XMP_NO_OWNER, XMP_NO_OWNER, XMP_NO_OWNER}, \
      0, XMP_NO_OWNER, XMP_MUTEX_FLAG_NORMAL, 0, 0, 0, name }

#define XMP_RECURSIVE_MUTEX_INITIALIZER(name)				\
  { 0, 0, -1, {XMP_NO_OWNER, XMP_NO_OWNER, XMP_NO_OWNER, XMP_NO_OWNER}, \
      0, XMP_NO_OWNER, XMP_MUTEX_FLAG_RECURSIVE, 0, 0, 0, name }

#define XMP_MUTEX_FLAG_NORMAL 0
#define XMP_MUTEX_FLAG_RECURSIVE 1

#define XMP_MUTEX_ACQUIRE_FAILED -1
#define XMP_MUTEX_ERROR_DESTROY_OWNED -2
#define XMP_MUTEX_ERROR_NOT_OWNED -3
#define XMP_MUTEX_ERROR_ALREADY_OWNED -4

/*
   xmp_mutex_init
   
   Nonsynchronizing
   Nonblocking 

   Usage: 
      mutex - points to an uninitialized mutex
      name - name if you want one, NULL if not.
      recursive - use recursive semantices      

   Returns
      zero on success (always succeeds)

*/

extern int xmp_mutex_init (xmp_mutex_t * mutex, 
			    const char * name, 
			    unsigned int recursive);

/*
   int xmp_mutex_destroy (xmp_mutex_t * mutex);
   
   Synchronizing - will fail if mutex is held by anyone -- including 
                   current processor
   Nonblocking 

   Usage: 
      mutex - points to a mutex

   Returns
      zero on success
      non-zero if mutex is held
*/

extern int xmp_mutex_destroy (xmp_mutex_t * mutex);


/*
   xmp_mutex_lock -- Synchronizing
   xmp_mutex_trylock

   Usage: 
      mutex - points to a mutex

   Returns
      zero on success
*/

extern int xmp_mutex_lock (xmp_mutex_t * mutex);
extern int xmp_mutex_trylock (xmp_mutex_t * mutex);


/*
   xmp_mutex_unlock
   
   Synchronizing
   Nonblocking 

   Usage: 
      mutex - points to a mutex

   Returns
      zero on success - mutex is released
      non-zero on failure - mutex is owned by another core 
                          - prid of processor that does own it
			    note that by the time this function
			    returns, the owner of the core may 
			    have changed.
*/

extern int xmp_mutex_unlock (xmp_mutex_t * mutex);


/*
   xmp_mutex_name
   
   Nonsynchronizing
   Nonblocking 

   Usage: 
      mutex - points to a mutex

   Returns the name of the given mutex, which may be NULL.
      
*/

const char * xmp_mutex_name (const xmp_mutex_t * mutex);


/* 
   xmp_mutex_trace_on
   xmp_mutex_trace_off

   Nonsynchronizing
   Nonblocking

   Turn off and on tracing for the mutex.

   These functions are only present in the debug version of the library.
*/

extern void xmp_mutex_trace_on (xmp_mutex_t * mutex);
extern void xmp_mutex_trace_off (xmp_mutex_t * mutex);


/* -------------------------------------------------------------------------
   xmp_condition_t

   Condition Variables following Mesa semantics. 

   Condition variables are not sharable among interrupt levels.

*/


typedef struct xmp_condition_t {
  unsigned int qhead;
  unsigned int qtail;
  unsigned char queue[XMP_MAX_CORES];
  unsigned int waiting[XMP_MAX_CORES];

  unsigned char trace : 1;
  unsigned char unused : 7;
  const char * name;
} xmp_condition_t __attribute__ ((aligned (XMP_MAX_DCACHE_LINESIZE)));


#define XMP_CONDITION_INITIALIZER(name)				\
  { 0, -1, {XMP_NO_OWNER, XMP_NO_OWNER, XMP_NO_OWNER, XMP_NO_OWNER}, \
      {0, 0, 0, 0}, 0, 0, name}


/* xmp_condition_init - Initialize a condition variable

   Nonsynchronizing, Nonblocking 

   Usage: 
      condition - pointer to an xmp_condition_t

   On exit:
      condition initialized

   Errors: none
*/

extern int xmp_condition_init (xmp_condition_t * condition, 
				const char * name);
extern int xmp_condition_destroy (xmp_condition_t * condition);


/* xmp_condition_wait - Wait for a condition variable

   Synchronizing, blocking 

   Usage: 
      condition - pointer to an xmp_condition_t
      mutex - pointer to an xmp_mutex_t already acquired by the calling
              process

   Errors: if the mutex isn't held by this core
*/

extern int xmp_condition_wait (xmp_condition_t * condition, 
				xmp_mutex_t * mutex);

/* xmp_condition_signal 

   - Signal the first (if any) core waiting on a condition variable

   You must hold the mutex you passed to xmp_condition_wait before
   calling this function.

   Synchronizing, nonblocking

   Usage: 
      condition - pointer to an xmp_condition_t

   Errors: none
*/

extern int xmp_condition_signal (xmp_condition_t * condition);


/* xmp_condition_broadcast

   - Signal all cores waiting on a condition variable

   Synchronizing, nonblocking

   You must hold the mutex you passed to xmp_condition_wait before
   calling this function.

   Usage: 
      condition - pointer to an xmp_condition_t

   Errors: none
*/

extern int xmp_condition_broadcast (xmp_condition_t * condition);


static inline const char * xmp_condition_name (const xmp_condition_t * condition)
{
  return condition->name;
}

/* 
   xmp_condition_trace_on
   xmp_condition_trace_off

   Nonsynchronizing
   Nonblocking

   Turn off and on statistics and tracing for the condition.  For
   tracing you must also set a trace file for the core.

   These functions are only present in the debug-version of the library.
*/

extern void xmp_condition_trace_on (xmp_condition_t * condition);
extern void xmp_condition_trace_off (xmp_condition_t * condition);

#endif /* XCHAL_DCACHE_IS_COHERENT */

/* -------------------------------------------------------------------------
   xmp_barrier_t

   Classic barriers that stop any core from continuing until a
   specified number of cores reach that point. Once the barrier allows
   cores through, the barrier is reset and will stop cores from
   progressing again.

   Barriers are not sharable among interrupt levels.

*/


typedef struct xmp_barrier_t 
{ 
  xmp_atomic_int_t count; 
  xmp_atomic_int_t state;
  xmp_atomic_int_t sleeping;
  unsigned short num_cores;
  unsigned short trace : 1;
  unsigned short system : 1;
  const char * name;
} xmp_barrier_t __attribute__ ((aligned (XMP_MAX_DCACHE_LINESIZE)));

#define XMP_BARRIER_INITIALIZER(number, name)	\
  { 0, 0, 0, number, 0, 0, name }


/* xmp_barrier_init - Initialize a barrier

   Nonsynchronizing, Nonblocking 

   Usage: 
      barrier - pointer to an xmp_barrier_t
      num_cores - number of cores needed to arrive at the 
                  barrier before any are allowed through
   On exit:
      barrier initialized

   Always returns zero.

   Errors: none
*/

extern int xmp_barrier_init (xmp_barrier_t * barrier, int num_cores, 
			      const char * name);


/* xmp_barrier_wait - Wait on a barrier

   Nonsynchronizing, Nonblocking 

   Usage: 
      barrier - pointer to an xmp_barrier_t
   On exit:
      Enough cores (as determined at the barrier's initialization)
      have reached the barrier.

   Errors: none
*/

extern int xmp_barrier_wait (xmp_barrier_t * barrier);


static inline const char * xmp_barrier_name (const xmp_barrier_t * barrier)
{
  return barrier->name;
}


/* 
   xmp_barrier_trace_on
   xmp_barrier_trace_off

   Nonsynchronizing
   Nonblocking

   Turn on and off tracing for the barrier.  For
   tracing you must also set a trace file for the core.

   These functions are only present in the debug-version of the library.
*/

extern void xmp_barrier_trace_on (xmp_barrier_t * barrier);
extern void xmp_barrier_trace_off (xmp_barrier_t * barrier);


/* -------------------------------------------------------------------------
   Portions of the library that are internal, but belong here for
   convenience.
*/

extern xmp_atomic_int_t _ResetSync;

static inline void 
xmp_initial_sync (int num_cores)
{
  xmp_atomic_int_increment (&_ResetSync, 1);
  while (xmp_coherent_l32ai (&_ResetSync) != num_cores)
    xmp_spin ();
}

#ifdef __cplusplus
}
#endif

#endif /* _XMP_LIBRARY_H */