/home/mesh/mesh/include/mesh_types.h

/*************************************************************************
    This file is part of MESH.

    MESH is free software: you can redistribute it and/or modify
    it under the terms of the GNU General Public License as published by
    the Free Software Foundation, either version 3 of the License, or
    (at your option) any later version.

    MESH is distributed in the hope that it will be useful,
    but WITHOUT ANY WARRANTY; without even the implied warranty of
    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
    GNU General Public License for more details.

    You should have received a copy of the GNU General Public License
    along with MESH.  If not, see <http://www.gnu.org/licenses/>.
**************************************************************************/

#ifndef MESH_TYPES_H
#define MESH_TYPES_H

#include <glib.h>
#include <gpriq.h>
#include <mesh.h>

struct mesh_thread_t;
struct mesh_pthread_t;
struct mesh_scheduler_t;
struct mesh_comm_scheduler_t;
struct mesh_interrupt_controller_t;
struct mesh_interrupt_t;
struct mesh_resource_t;
struct mesh_consume_data_t;
struct mesh_resource_thread_pair_t;
struct mesh_feature_power_pair_t;
struct mesh_resource_time_pair_t;
struct mesh_thread_mutex_t;
struct mesh_thread_cond_t;
struct mesh_thread_sem_t;
struct mesh_synchronization_t;
struct mesh_trace_event_t;
struct mesh_shared_data_t;
struct mesh_comm_thread_data_t;
struct mesh_delayed_comm_event_t;
struct mesh_mem_controller_t;
struct mesh_mem_resource_t;
struct mesh_SR_slice_t;
struct mesh_access_statistics_t;
typedef struct mesh_thread_t mesh_thread;
typedef struct mesh_pthread_t mesh_pthread;
typedef struct mesh_scheduler_t mesh_scheduler;
typedef struct mesh_comm_scheduler_t mesh_comm_scheduler;
typedef struct mesh_interrupt_controller_t mesh_interrupt_controller;
typedef struct mesh_interrupt_t mesh_interrupt;
typedef struct mesh_resource_t mesh_resource;
typedef struct mesh_consume_data_t mesh_consume_data;
typedef struct mesh_resource_thread_pair_t mesh_resource_thread_pair;
typedef struct mesh_feature_power_pair_t mesh_feature_power_pair;
typedef struct mesh_resource_time_pair_t mesh_resource_time_pair;
typedef struct mesh_thread_mutex_t mesh_thread_mutex;
typedef struct mesh_thread_cond_t mesh_thread_cond;
typedef struct mesh_thread_sem_t mesh_thread_sem;
typedef struct mesh_synchronization_t mesh_synchronization;
typedef struct mesh_trace_event_t mesh_trace_event;
typedef struct mesh_shared_data_t mesh_shared_data;
typedef struct mesh_memcpy_data_t mesh_memcpy_data;
typedef struct mesh_comm_thread_data_t mesh_comm_thread_data;
typedef struct mesh_delayed_comm_event_t mesh_delayed_comm_event;
typedef struct mesh_mem_controller_t mesh_mem_controller;
typedef struct mesh_mem_resource_t mesh_mem_resource;
typedef struct mesh_SR_slice_t mesh_SR_slice;
typedef struct mesh_access_statistics_t mesh_access_statistics;
typedef GSList mesh_feature_list;
typedef double mesh_time;

struct mesh_scheduler_t {
    gchar *name;
    GSList *bound_threads; // array of pointers to thread structures
    GSList *eligible_threads; // array of pointers to eligible threads
    GSList *controlled_resources; //list of resources controlled by scheduler
    GSList *(*execute_scheduler)(mesh_scheduler *scheduler);
    void (*execute_shared)(mesh_scheduler *, GSList *shared_info, mesh_time);
    gint index;
    gboolean on_todo_list;  //indicates whether this scheduler is set to run

    GHashTable *comm_thread_hash; //contains a hash of comm thread
                                  //names to function pointers

    GHashTable *entry_map; // storage for arbitrary user data

    //indicates whether this scheduler controls shared resources
    gboolean is_shared;

    mesh_resource *sched_resource;  //holds scheduling resource in case
    //of centralized schedulers
};

typedef enum { EXEC_THREAD, COMM_THREAD, ISR_THREAD } mesh_thread_type;
typedef enum { POLICY_DEFAULT=-1, POLICY_PINNED, POLICY_COARSE, POLICY_FINE } mesh_scheduling_policy;

// the communication scheduler assigns comm events to resources via
// comm_threads.  Therefore, it does not need to have a scheduling
// function associated with it
struct mesh_comm_scheduler_t {
    gchar *name;
    GHashTable *comm_thread_hash;  //contains a hash of comm_thread names
    //to function pointers
};

struct mesh_pthread_t {
    // these are used for the consume calls to allow only one
    // section of code to execute at once
    pthread_cond_t cond_local;  pthread_mutex_t mutex_local;
    pthread_cond_t cond_kernel; pthread_mutex_t mutex_kernel;

    // variables for the above conditions
    gboolean kernel_ready, local_ready;

    // the pthread id of this user thread
    pthread_t tid;

    // the current mesh thread
    mesh_thread *ct;
};

struct mesh_thread_t {
    gchar *name;
    
    mesh_scheduler *execution_scheduler;
    void * (*thread)(void *);

    mesh_pthread *pt;
    
    //holds the list of consume calls that have been provided by the
    //application thread, but are not on the priority queue.  This
    //situation occurs when an interrupt occurs.  In that case, the
    //second part of the consume split by the interrupt is placed on
    //the outstanding_consumes list.  This list will grow in size if
    //nested interrupts occur.
    GList *outstanding_consumes;

    //current_consume holds the consume call that is currently being
    //filled by the lightweight consumes (i.e. it's lw_consumes list
    //is being populated).  This should be NULLed each time thread is
    //context switched into
    mesh_consume_data *current_consume;
    
    // the thread id assigned by the simulator
    gint thread_id;

    // a flag indicating if this thread is an untimed
    gboolean untimed;

    // indicates if this thread is a comm_thread, exec_thread, or isr_thread
    mesh_thread_type type;

    //a flag indicating that the thread should be canceled after the
    //completion of the next consume call
    gboolean cancel_me;

    // indicates that the thread has been squashed and should exit immediately
    gboolean squashed;

    // a flag indicating if the thread has finished executing and
    // can be terminated
    gboolean finished;

    // a flag indicating if the kernel is done with the thread
    gboolean dead;

    // a flag indicating if this thread has stalled on a synchronization
    // primitive
    mesh_synchronization *stalled;
    
    // has this thread been started
    gboolean started;

    // the scheduling policy for this thread
    mesh_scheduling_policy scheduling_policy;
    
    //pointer to the resource this thread was last run on
    mesh_resource *last_run_on;

    
    // this is a pointer that the user process can access to
    // store thread specific data
    void *user_data;
    GHashTable *entry_map;      /* used to store data for mesh extensions */

    double user_counter;

    double usage;  //number of cycles this thread ran
    double contention; //number of cycles thread was contended for
    
    // this synchronization primitive is used by threads wishing
    // to join on this one, in order that they may block and allow the
    // kernel to regain control
    mesh_synchronization *synch;
    void *retval;

    // Following are lists of delayed events, things that should
    // happen at the end of the consume call
    GSList *delayed_created_threads;
    GSList *delayed_free; // a list of pointers to free
    GSList *delayed_memcpy; // this is a list of mesh_memcpy_data structs
    GSList *delayed_synchronization; // list of delayed synch wakeups
    GSList *delayed_comm_events; //delayed comm read/writes

    // Interrupt stuff
    GSList *disabled_interrupts;
    gboolean all_interrupts_disabled;

    // argument to pass the thread
    void *arg;
};

struct mesh_interrupt_t
{
    gchar *name;
    gboolean maskable;
    void *(*isr)(void *);
    void *user_data;    // arg passed to isr()
};

struct mesh_interrupt_controller_t
{
    // arg passed to the contrpoller function
    void *user_data;    
        
    // The interrupt controller function. Takes in a list of pending
    // interrupts and chooses one to run
    char* (*controller)(void *, GSList **pending);
        
    GHashTable *interrupt_table; // maps interrupts to their handlers

    // lists of interrupt names
    GSList *pending;

    // active ISR threads (LIFO/stack)
    GSList *active;
};

// the SR slice struct is essentially a mesh_consume_data structure
// for a single lightweight consume call (i.e. a "slice")
struct mesh_SR_slice_t {
    mesh_time end_time;
    mesh_time length;
    GSList *utilization;
    mesh_resource *cr;
};

struct mesh_access_statistics_t {
    float util;
    float align;
};

struct mesh_mem_controller_t {
    gchar *name;
    gint (*schedule_mem)(gint res_id, gint block_id);
    GArray *mem_resource_list; //array of memory resources controlled
};

struct mesh_mem_resource_t {
    gchar *name;
    double time_per_access;  //multiplier that transforms number of
                             //accesses into time necessary to service
                             //those accesses without contention
    gint mem_res_id; //resource id, position of resource in
                     //mem_resource_list

    //pointer to the contention model resolving access statistics into
    //delay
    float (*contention_model)(mesh_access_statistics *);

    //pointer to the arbitration model that distributes delay among
    //consume calls
    void (*arbitration_model)(float, GPriq *);
};

struct mesh_resource_t {
    gchar *name;
    mesh_scheduler *cs;
    mesh_thread *last_thread ; // last thread to execute on this resource

    mesh_thread *delay_thread; // thread used for mesh_consume_delay
        
    // interrupt controller
    mesh_interrupt_controller interrupt_controller;

    // function to take a list of feature arrays, and return the total
    // time needed to execute on this execution resource
    double (*exec_timing_resolution)(mesh_resource *, GSList *);

    //same as above, just for shared resources
    double (*sr_timing_resolution)(mesh_resource *, double *);

    //function that estimates the amount of contention penalty that
    //results from multiple accesses to one shared resource
    void (*contention_resolution)(mesh_resource *, GSList *, mesh_time);
    
    mesh_feature_list *cfl; // list of features provided and their power
    gboolean idle;  //indicates that the resource is idle
    double sr_penalty;  //penalty due to shared resource contention
    double sch_penalty; //penalty due to scheduler execution

    double usage;       //number of cycles this resource was used
    //(including sch_usage)

    double sch_usage;   //number of cycles this resource was used for
    //scheduling

    gint res_id;   //resource id, position of resource in resource_list

    gboolean trace_visible; //sets whether the resource should be
    //included in the trace output

    gboolean shared;  //is this a shared resource

    mesh_thread *blocked; //is this resource blocked by a comm. thread

    void *user_data; //pointer user may use to store data for mesh extensions

    GHashTable *entry_map;      /* used to store data for mesh extensions */

    mesh_mem_controller *mem_controller; //any memory accesses
                                         //performed by this resource
                                         //must be handled by this
                                         //mem_controller
};

struct mesh_consume_data_t {
    mesh_time length;
    mesh_time end_time;
    mesh_time sr_penalty;  //shared resource penalties
    mesh_time sch_penalty; //penalty due to scheduler execution on
    //this resource

    // list of mesh lightweight consume calls.  Each consume call
    // contains a GSList of feature_arrays which are of type double*.
    // Most of the time, each lw consume will contain only one
    // feature_array.  However, if [...] notation is used within the
    // consume call to give the timing resolution function a choice,
    // more than one feature_array will be included. This allows one
    // set of annotations to handle multiple types of processors
    // (i.e. with FP unit or without)
    GSList *lw_consumes;
    GSList *lw_consumes_tail;

    GSList *mem_arguments;
    GSList *mem_arguments_tail;
    
    mesh_resource *cr;  //name of resource that this consume data is
                        //executed on
    mesh_thread *ct;
    mesh_scheduler *exec_scheduler;
    gboolean ends_with_interrupt;
    gint slices_processed;  //flag which is set once all the SR slices
                            //of the consume call are processed.
                            //Avoids duplication of that work
    gchar *name;
};

struct mesh_resource_thread_pair_t {
    mesh_thread *thread;
    mesh_resource *resource;
};

struct mesh_resource_consume_pair_t {
    mesh_consume_data *consume_data;
    mesh_resource *resource;
};

struct mesh_feature_power_pair_t {
    gint feature;
    double power;
};

struct mesh_resource_time_pair_t {
    mesh_resource *cr;
    mesh_time t;
};

struct mesh_thread_mutex_t {
    mesh_synchronization *cs;
};

struct mesh_thread_cond_t {
    mesh_synchronization *cs;
};

struct mesh_thread_sem_t {
    mesh_synchronization *cs;
    int semaphore_value; // value of the semaphore
};

struct mesh_synchronization_t {
    GSList *stalled_threads; // list of threads stalled on this primitive
    int type; // 0=mutex 1=condition variable 2=thread 3=semaphore
    gboolean mutex_flag; // whether or not the mutex is locked
};

//a single link for the event chain interpreted by the trace parser
struct mesh_trace_event_t {
    mesh_time time_step;
    mesh_time global_time;
    mesh_time mesh_length;
    gchar *name;
    mesh_resource *resource; //comm resource
    mesh_thread *ct; //comm thread
    mesh_resource *exec_resource; //calling execution resource 
    mesh_thread *exec_thread;//calling execution thread
    mesh_time sr_penalty;   //penalty due to shared resource contention
    mesh_time sch_penalty;  //penalty due to scheduler overhead
    gint type;              //defines the type of the event:
    //0 = exec
    //1 = comm
    //2 = testbench
};

struct mesh_memcpy_data_t {
    const void *src;
    void *dest;
    size_t n;
};

struct mesh_shared_data_t {
    int id;                   //ID that identifies each unique shared data
    void *data;               //payload field
    int status;               //shows the status of the shared variable
    // 0 = Inactive
    // 1 = Shared (multiple concurrent reads)
    // 2 = Exclusive (writing)
    // 3 = Exclusive Request (request to write)

    mesh_thread_cond *cond;   //condition var to protect the status
    mesh_thread_mutex *mutex; //mutex for the condition variable
    GSList *pending_reads;    //list of threads waiting for a read on this
    //shared data
};

struct mesh_comm_thread_data_t {
    int func;    //task to perform
    // 0 = read
    // 1 = write
    
    mesh_shared_data *data;
    void *arg;   //other arguments to be used by the comm_thread

    // calling resource and thread
    mesh_resource *exec_resource;
    mesh_thread *exec_thread;
};

//storage for all the information necessary for delay of read/write
//communication events
struct mesh_delayed_comm_event_t {
    mesh_scheduler *cs;
    gchar *comm_thread;
    mesh_comm_thread_data *comm_thread_data;
    gchar *thread_name;
    gint blocking_mode;
};

#endif