trt.h

Go to the documentation of this file.

/*--------------------------------------------------------------------
 *
 * (C) Copyright Koninklijke Philips Electronics NV 2006. 
 * All rights reserved. This software is licensed under the terms of
 * version 2.1 of the GNU Lesser General Public License as published 
 * by the Free Software Foundation. For licensing and warranty
 * information, see the file COPYING in the main directory.
 *
 *------------------------------------------------------------------*/

#ifndef TRT_H
#define TRT_H

#include <setjmp.h>
#include <stdlib.h>
#include <assert.h>
#include <time.h>
#include <atomic.h>

/* limits and configuration settings ******************************************/

#define TRT_MAX_NUM_PROCESSORS_PER_TILE   16

#define TRT_SCHEDULER_STACK_SIZE  128
#define TRT_STACK_OVERFLOW_MAGIC  0x02742312

#define TRT_STATISTICS    1

#define TRT_ISA_MIPS      0
#define TRT_ISA_I386      1
#define TRT_ISA_SPARC     2
#define TRT_ISA_HPPA      3

#define WHERE serial_out("line %d of %s\n", __LINE__, __FILE__);

/* settings from trtconfig.c **************************************************/

extern int trt_config_stack_size;

/* data structures ************************************************************/

typedef struct thread_s thread_t;
typedef struct semaphore_s semaphore_t;
typedef struct processor_s processor_t;
typedef struct mutex_s mutex_t;
typedef struct cond_s cond_t;
typedef struct atexit_s atexit_t;
typedef struct domain_s domain_t;
typedef union  context_s context_t;
typedef struct sym_s sym_t;
typedef struct sym_table_s sym_table_t;
typedef struct thread_table_s thread_table_t;

struct semaphore_s
{
  int count;              /* value of semaphore */
  thread_t *blocked_head; /* list of blocked threads */
  thread_t *blocked_tail;
  int blocked_lock;       /* spin lock for blocked list */
  char *name;             /* its name (for debuging) */
};

struct atexit_s
{
  void (*fun[5])(int);    /* functions to be called */
  int arg[5];             /* their args */
  short count;            /* number of functions */
  char free_desc;         /* free thread_t on exit */
  char free_stack;        /* free stack on exit */
};

union context_s
{
  jmp_buf context;
};

struct thread_s
{
  context_t context;      /* registers, stack pointer, pc */
  int (*start_fun)(int);  /* start function and its argument */
  int start_arg;    
  int *stack;             /* malloced memory for stack */
  int *stack_init_sp;     /* initial sp */
  int *stack_magic;       /* for stack overflow testing */
  semaphore_t exit;       /* waiting for a thr_join() */
  char *name;             /* thread name, is not strdup'ed */
  int exit_status;        /* status passed from exit -> join */
  int suspension_mode;    /* SUSPEND_DISABLE/SUSPEND_ENABLE */
  semaphore_t *suspend_point_sem;
  processor_t *processor; /* (last time) running on this proc. */
  thread_t *next;         /* to put threads in lists */
  semaphore_t *blocked_on;/* blocked on which sem? NULL if not */
  atexit_t atexit;        /* things to do on exit */
  void (*block_handler)();/* to be called when blocked */
  unsigned int id;        /* thread ID: 0, 1, 2, ... */
  thread_t *next_table;   /* to put thread in trt_thread_table */
  thread_t *prev_table;
  unsigned int task_id;   /* written to TRT_TASK_ID on ctx sw */
};

struct domain_s           /* scheduling domain */
{
  int isa;                /* instruction set architecture */
  long num_context_switches;/* statistics */
  long num_thread_migrates; /* statistics */
};

struct processor_s
{
  int index;                /* unique id: 0, 1, 2, ... */
  domain_t *domain;         /* scheduling domain */
  int purpose;              /* general or special purpose? */
  thread_t *running_thread; /* currently running thread */
  thread_t *ready_list_head;/* ready list */
  thread_t *ready_list_tail;
  int ready_list_lock;
  thread_t *schedule_me;    /* "one element ready list" */
  thread_t crt0_thread;
  int scheduler_stack[TRT_SCHEDULER_STACK_SIZE];  /* stack for scheduler */
  void (*volatile idle_handler)(void);            /* called when idle */
  unsigned long idle_spin_count;                  /* used for thread stealing heuristic */
};

struct thread_table_s
{
  thread_t *head;     /* first thread */
  thread_t *tail;     /* last thread */
  int lock;           /* lock for mutual exclusion */
};

struct mutex_s
{
  semaphore_t lock;
};

struct cond_s
{
  semaphore_t queue;
};

enum suspend_modes
{
  SUSPEND_ENABLE = 0, SUSPEND_DISABLE
};

struct sym_s
{
  int isa;        /* which architecture */
  int hash;       /* hash value */
  char *name;     /* symbol name */
  void *addr;     /* symbol value */
  sym_t *next;    /* to put symbols in lists */
};

struct sym_table_s
{
  int lock;
  sym_t *list[19];
};

extern processor_t *current_processor;
#define get_current_processor()   (current_processor)
#define set_current_processor(p)  (current_processor = (p))

extern int trt_tile_idx;

/* semaphore/mutex/condition variable initializers */
#define SEM_INITIALIZER(c, n)     {(c), 0, 0, 0, (n)}
#define MUT_INITIALIZER           {SEM_INITIALIZER(1, "mut")}
#define CND_INITIALIZER           {SEM_INITIALIZER(0, "cnd")}

/* force load of volatile thread_t * variable (which is not declared as volatile) 
 */
#define force_load(var)                   \
(                 \
  *(thread_t * volatile *) &(var)         \
)

#if __cplusplus
extern "C" {
#endif

/* system functions ***********************************************************/

/*
 * initialize processor for trt. should be called on every processor.
 */
void trt_init(int *stack_bot, int *stack_top);

/*
 * return number of tiles in system.
 */
int trt_num_tiles();

/*
 * set scheduling domain for a processor.
 */
void trt_set_scheduling_domain(int processor_index, domain_t *domain);

/*
 * return scheduling domain for a processor.
 */
domain_t *trt_scheduling_domain(int processor_index);

/*
 * move thread to processor of specified scheduling domain.
 */
void thr_migrate_domain(thread_t *thread, domain_t *domain);

/*
 * initialize scheduling domain.
 */
void trt_init_scheduling_domain(domain_t *domain, int isa);

/*
 * return index of processor on which this function is called.
 */
static inline int trt_processor_index()
{
  return get_current_processor()->index;
}

/*
 * return index of the tile on which this function is called.
 */
static inline int trt_tile_index()
{
  return trt_tile_idx;
}

/* thread management functions ************************************************/

/*
 * create a new thread. parameters are start function and its argument.
 * the thread has to be started with thr_start and will be executed on
 * the same architecture as the calling processor.
 */
void thr_create(thread_t *new_thread, int (*fun)(int), int arg);

/*
 * destroy a thread. it is only necessary to call this function if
 * the thread did not do an thr_exit() itself. you should only call this
 * function when the thread is blocked or suspended.
 */
void thr_destroy(thread_t *thread);

/*
 * create a new thread for specified architecture.
 */
//void thr_create_isa(thread_t *new_thread, int isa, char *fun_name, int arg);

void thr_stack_size(thread_t *thread, int size);

void thr_stack_addr(thread_t *thread, void *addr);

/*
 * lookup thread in trt_thread_table.
 */
thread_t *thr_lookup(int id);

/*
 * set cache and ddr domain of thread
 */
void thr_set_cache_ddr_domain(thread_t *thread, int cache_domain, 
                                                int ddr_domain);

/*
 * exit current thread. exit status is passed to thread that joins this thread.
 */
void thr_exit(int exit_status);

/*
 * call fun(arg) on exit of this thread.
 */
void thr_atexit(thread_t *thread, void (*fun)(int), int arg);

/*
 * remote function from at exit list. execute it optionally.
 */
void thr_atexit_pop(thread_t *thread, int execute);

/*
 * call this function on blocking of this thread.
 */
void thr_onblock(thread_t *thread, void (*fun)(void));

/*
 * call this function when tile is idle.
 */
void trt_onidle(void (*fun)(void));

/*
 * return load on tile (number of running/ready threads).
 */
int trt_load();

/*
 * return number of (general purpose) processors of type ISA.
 */
int trt_num_procs(int isa);

/*
 * are there no running threads?
 */
int trt_is_idle();

/*
 * start newly created thread.
 */
void thr_start(thread_t *thread);

/*
 * stop thread. thread has to be suspended first.
 */
void thr_stop(thread_t *thread, int status);

/*
 * suspend thread execution.
 */
void thr_suspend(thread_t *thread);

/*
 * resume thread execution.
 */
void thr_resume(thread_t *thread);

/*
 * restart process with specified function and argument. thread has to be
 * suspended first.
 */
void thr_restart(thread_t *thread, int (*fun)(int), int arg);

/*
 * suspend myself (helper function for thr_suspend_point)
 */
void thr_suspend_me();

/*
 * suspend in case there is a suspension request pending. 
 */
static inline void thr_suspend_point()
{
  if(get_current_processor()->running_thread->suspend_point_sem)
    thr_suspend_me(); 
}

/*
 * set suspend mode (SUSPEND_ENABLE, SUSPEND_DISABLE). return prev mode.
 */
int thr_suspend_mode(thread_t *thread, int mode);

/*
 * wait until specified thread exits. 
 */
void thr_join(thread_t *thread, int *exit_status);

/*
 * do a context switch, ie. give up processor.
 */
void thr_switch();

/*
 * specify thread name.
 */
void thr_set_name(thread_t *thread, char *name);


/* 
 * return thread name.
 */
static inline char *thr_name(thread_t *thread)
{
        return thread->name;
}

/*
 * return start argument of thread.
 */
static inline int thr_argument(thread_t *thread)
{
        return thread->start_arg;
}

/*
 * who am i?
 */
static inline thread_t *thr_self()
{
        return get_current_processor()->running_thread;
}

/*
 * return processor index on which thread is running ([0..N-1]).
 */
static inline int thr_processor_index(thread_t *thread)
{
  return thread->processor->index;
}

int thr_isa(thread_t *thread);
char *thr_isa_name(thread_t *thread);

/* semaphore functions ********************************************************/

/* 
 * initialize semaphore with specified value.
 */
void sem_init(semaphore_t *semaphore, int init, char *name);

/* 
 * do a Pn on semaphore.
 */
int sem_Pn(semaphore_t *semaphore, int n);

/*
 * reset value of semaphore, return previous value.
 */
static inline int sem_reset(semaphore_t *semaphore)
{
  return atomic_seti(semaphore->count, 0);
}

/* 
 * do a Vn on semaphore.
 */
void sem_Vn(semaphore_t *semaphore, int n);

/* 
 * add me to blocked list of semaphore.
 */
void sem_block_me(semaphore_t *semaphore);

/* 
 * remove someone from blocked list of semaphore.
 */
void sem_unblock_someone(semaphore_t *semaphore);

/* 
 * do a P on semaphore.
 */
static inline void sem_P(semaphore_t *semaphore)
{
  if(atomic_subi(semaphore->count, 1) <= 0)
    sem_block_me(semaphore);
}

/* 
 * do a V on semaphore.
 */
static inline void sem_V(semaphore_t *semaphore)
{
  if(atomic_addi(semaphore->count, 1) < 0)
    sem_unblock_someone(semaphore);
}

/* 
 * do a Pn on semaphore which should not block (nb = nonblocking).
 */
static inline void sem_Pn_nb(semaphore_t *semaphore, int n)
{
  atomic_sub(semaphore->count, n);
}

/* 
 * do a Vn on a private semaphore (max one thread blocked).
 */
static inline void sem_Vn_priv(semaphore_t *semaphore, int n)
{
  if(atomic_add(semaphore->count, n) < 0)
    sem_unblock_someone(semaphore);
}

/*
 * try to do a P without blocking. returns true if successful.
 */
static inline int sem_tryP(semaphore_t *semaphore)
{
  if(atomic_subi(semaphore->count, 1) <= 0)
  {
    atomic_addi(semaphore->count, 1);

    return 0;
  }
  
  return 1;
}

/*
 * return value of semaphore.
 */
static inline int sem_value(semaphore_t *semaphore)
{
  return *(volatile int *) &semaphore->count;
}


/* mutexes and condition variables functions **********************************/

/*
 * initialize a mutex.
 */
static inline void mut_init(mutex_t *mutex)
{
  sem_init(&mutex->lock, 1, "mutex");
}

/*
 * lock a mutex.
 */
static inline void mut_lock(mutex_t *mutex)
{
  sem_P(&mutex->lock);
}

/*
 * unlock a mutex.
 */
static inline void mut_unlock(mutex_t *mutex)
{
  sem_V(&mutex->lock);
}

/*
 * initialize a condition variable.
 */
static inline void cnd_init(cond_t *cond)
{
  sem_init(&cond->queue, 0, "cond");
}

/*
 * wait on a condition.
 */
static inline void cnd_wait(cond_t *cond, mutex_t *mutex)
{
  sem_V(&mutex->lock);
  sem_P(&cond->queue);
  sem_P(&mutex->lock);
}

/*
 * signal a condition.
 */
static inline void cnd_signal(cond_t *cond)
{
  if(cond->queue.count < 0)
    sem_V(&cond->queue);
}

/*
 * signal a condition to all waiting threads.
 */
static inline void cnd_broadcast(cond_t *cond)
{
  int count = cond->queue.count;

  while(count-- > 0)
    sem_V(&cond->queue);
}

/* symbol exchange between executables ****************************************/

void sym_register(char *name, void *addr);
void *sym_query(int isa, char *name, int wait);
void sym_dump();

/* serial out *****************************************************************/

void serial_out(char *format, ...);
void trt_putc(int port, char c);
int trt_getc(int port);

/* panic **********************************************************************/

void trt_panic(char *error_message);
void trt_panic_d(char *error_message, int arg);
void trt_panic_s(char *error_message, char *arg);

/* debug stuff ****************************************************************/

void trt_debug_handler(char *name, void (*handler)(char *), char *help);
void thr_dump_info(thread_t *thread, int header);

/* our own malloc *************************************************************/

void *trt_malloc(unsigned int);
void trt_free(void *p);

#if __cplusplus
}
#endif
#endif

---