Main Page | Namespace List | Class Hierarchy | Class List | File List | Namespace Members | Class Members | File Members

rk_stub.h

Go to the documentation of this file.
00001 /*
00002  * rk_stub.h
00003  *
00004  * Copyright (c) 2003 The University of Utah and the Flux Group.
00005  * All rights reserved.
00006  *
00007  * This file is licensed under the terms of the GNU Public License.  
00008  * See the file "license.terms" for restrictions on redistribution 
00009  * of this file, and for a DISCLAIMER OF ALL WARRANTIES.
00010  */
00011 
00012 /**
00013  * @file rk_stub.h
00014  *
00015  * The simulator specific structures and function.
00016  *
00017  * @sa rk.h
00018  */
00019 
00020 #ifndef _rk_stub_h
00021 #define _rk_stub_h
00022 
00023 #include <stdio.h>
00024 
00025 #include <sys/types.h>
00026 #include <sys/time.h>
00027 #include <sys/resource.h>
00028 
00029 #include <listNode.h>
00030 
00031 #include "rk.h"
00032 
00033 #ifdef __cplusplus
00034 extern "C" {
00035 #endif
00036 
00037 /**
00038  * Forward declaration of the CPU reservation structure.
00039  */
00040 typedef struct cpu_reserve *cpu_reserve_t;
00041 
00042 /*
00043  * The rk_resource_set is the root structure for resource allocations.
00044  *
00045  * rs_Link - Linked list node.
00046  * rs_Name - Statically allocated memory for the set name.
00047  * rs_ProcessID - The simulated pid_t this set is attached too.
00048  * rs_CPU - The CPU reservation for this set.
00049  */
00050 struct rk_resource_set {
00051     struct lnMinNode rs_Link;
00052     char rs_Name[RSET_NAME_LEN];
00053     pid_t rs_ProcessID;
00054     cpu_reserve_t rs_CPU;
00055 };
00056 
00057 /**
00058  * The rk_cpu_reserve_trace_t type enumerates the set of trace files generated
00059  * by the stubs.
00060  *
00061  * @e NOTE: Update rk_cpu_trace_names in the source file if you make any
00062  * changes.
00063  */
00064 typedef enum {
00065     RK_CPU_TRACE_PERIOD,        /**< Process period. */
00066     RK_CPU_TRACE_DEADLINE,      /**< Process deadline, relative to the period.
00067                                  */
00068     RK_CPU_TRACE_COMPLETE,      /**< Completion of data processing. */
00069     RK_CPU_TRACE_DROP,          /**< Data dropped before processing. */
00070     RK_CPU_TRACE_REALTIME,      /**< Exact CPU time required to meet the
00071                                      deadline. */
00072     RK_CPU_TRACE_COMPUTE_SUCCESS,       /**< Actual CPU time, for successful
00073                                              periods. */
00074     RK_CPU_TRACE_COMPUTE_FAIL,  /**<  Actual CPU time, for failed periods. */
00075     RK_CPU_TRACE_MAX
00076 } rk_cpu_reserve_trace_t;
00077 
00078 enum {
00079     CRB_RUNNING,
00080 };
00081 
00082 /*
00083  * Flags for struct cpu_reserve.
00084  *
00085  * CRF_RUNNING - Indicates whether or not the process is currently running on
00086  *               the CPU.
00087  */
00088 enum {
00089     CRF_RUNNING = (1L << CRB_RUNNING),
00090 };
00091 
00092 /*
00093  * The cpu_reserve is used to trace CPU usage for a resource set.  The majority
00094  * of the data structure is devoted to tracking the CPU time periods and the
00095  * data progress periods.  Basically, we need to know not only when the
00096  * scheduler will give the process CPU time, but also whether or not it is
00097  * processing its data on time.  For example, if the process was not given
00098  * enough compute_time and is taking 50% longer to process the inputs its data
00099  * periods will not match the CPU periods.
00100  *
00101  * CPU   |---|  |---|  |---|  |---|   where:   | -> Period begin/end
00102  * DATA  |---+  +-|-+  +---|  |---+            + -> Period continued
00103  *
00104  * cr_Attributes - The current reservation spec.
00105  * cr_Flags - The holder for the above CRF_* flags.
00106  * cr_Compute.cr_Times - The CPU times required to meet the deadline for a
00107  *                       given period.  The times are looped so accesses must
00108  *                       be modded with the length.
00109  * cr_Compute.cr_Length - The number of elements in cr_Times.
00110  * cr_Compute.cr_DataIndex - The current data set being processed.  In other
00111  *                           words, the task has processed this many data
00112  *                           inputs.
00113  * cr_Compute.cr_TimeIndex - The current period index.  In other words, the
00114  *                           task has been scheduled and run for this many
00115  *                           periods.
00116  * cr_Compute.cr_DataPeriodStart - The start of the current data processing
00117  *                                 period.
00118  * cr_Compute.cr_DataPeriodEnd - The end of the current data processing period.
00119  * cr_Compute.cr_DataPeriodNext - The start of the next data processing period.
00120  * cr_Compute.cr_DataPeriodRemaining - The amount of processing left in the
00121  *                                     data period.
00122  * cr_Compute.cr_TimePeriodStart - The start of the current CPU period.
00123  * cr_Compute.cr_TimePeriodEnd - The end of the current CPU period.
00124  * cr_Compute.cr_TimePeriodNext - The start of the next CPU period.
00125  * cr_Trace - The trace files as enumerated above.
00126  */
00127 struct cpu_reserve {
00128     struct cpu_reserve_attr cr_Attributes;
00129     
00130     unsigned long cr_Flags;
00131     struct {
00132         struct timespec *cr_Times;
00133         unsigned int cr_Length;
00134         unsigned int cr_DataIndex;
00135         unsigned int cr_TimeIndex;
00136         
00137         struct timespec cr_DataPeriodStart; // Inclusive
00138         struct timespec cr_DataPeriodEnd; // Exclusive
00139         struct timespec cr_DataPeriodNext; // Inclusive
00140         struct timespec cr_DataPeriodRemaining; // Length
00141         
00142         struct timespec cr_TimePeriodStart; // Inclusive
00143         struct timespec cr_TimePeriodEnd; // Exclusive
00144         struct timespec cr_TimePeriodNext; // Inclusive
00145     } cr_Compute;
00146     FILE *cr_Trace[RK_CPU_TRACE_MAX];
00147 };
00148 
00149 enum {
00150     PCBB_IN_USE,
00151 };
00152 
00153 /*
00154  * Flags for rk_stub_pcb.
00155  *
00156  * PCBF_IN_USE - Indicates that the rk_stub_pcb object has been allocated.
00157  */
00158 enum {
00159     PCBF_IN_USE = (1L << PCBB_IN_USE),
00160 };
00161 
00162 /**
00163  * The rk_stub_precall_retval_t type enumerates the possible return values for
00164  * an rk_stub_precall_t call back.
00165  */
00166 typedef enum {
00167     RKSP_OK,    /**< Simulation of the data period should continue as normal */
00168     RKSP_DROP,  /**< The data has been dropped, move to the next period. */
00169 } rk_stub_precall_retval_t;
00170 
00171 /**
00172  * Prototype for the pre-data-period process call back.  These functions are
00173  * called before a new data period is simulated.
00174  *
00175  * @param data The process specific data.
00176  * @return An rk_stub_precall_retval_t value.
00177  */
00178 typedef rk_stub_precall_retval_t (*rk_stub_precall_t)(void *data);
00179 
00180 /**
00181  * Prototype for the post-data-period process call back.  These functions are
00182  * called after a data period has been simulated.
00183  *
00184  * @param data The process specific data.
00185  */
00186 typedef void (*rk_stub_postcall_t)(void *data);
00187 
00188 /*
00189  * The rk_stub_pcb stores any information needed for simulated processes.
00190  *
00191  * p_Name - The name of the process.
00192  * p_Flags - The holder for the above PCBF_* flags.
00193  * p_Data - Refers to any process specific data.
00194  * p_Precall - Function pointer that gets called before a data period begins,
00195  *             the argument is the value in p_Data.
00196  * p_Postcall - Function pointer that gets called after a data period ends,
00197  *              the argument is the value in p_Data.
00198  * p_Resources - The resource allocation for this process.
00199  */
00200 struct rk_stub_pcb {
00201     const char *p_Name;
00202     unsigned long p_Flags;
00203     void *p_Data;
00204     struct rusage p_Usage;
00205     rk_stub_precall_t p_Precall;
00206     rk_stub_postcall_t p_Postcall;
00207     rk_resource_set_t p_Resources;
00208 };
00209 
00210 /**
00211  * The rk_stub_mode_t type enumerates the set of modes the rk_stub code can
00212  * support.
00213  */
00214 typedef enum rk_stub_mode_t {
00215     RK_STUB_MIN,
00216     RK_STUB_LOG,        /**< Log all rk_* function calls. */
00217     RK_STUB_SIM,        /**< Same as RK_STUB_LOG, plus the simulator. */
00218     RK_STUB_MAX
00219 } rk_stub_mode_t;
00220 
00221 /**
00222  * Initialize the stub code and set the desired mode.
00223  *
00224  * @param mode One of the values in rk_stub_mode_t.
00225  */
00226 void rk_stub_set_mode(rk_stub_mode_t mode);
00227 
00228 /**
00229  * Advance the simulated time.  Simulated time starts at zero and then
00230  * continually advances to the next simulated event, such as a period end.
00231  */
00232 void rk_stub_next_tick(void);
00233 
00234 /**
00235  * Make a simulated process that will "consume" resources during its period.
00236  *
00237  * @sa rk_resource_set_attach_process
00238  * @sa rk_resource_set_detach_process
00239  *
00240  * @param name The name of the process.
00241  * @param data Process specific data, if any.
00242  * @param precall Function to call before a data period begins, can be NUL.
00243  * @param postcall Function to call after a data period ends, can be NULL.
00244  * @return The pid_t for the simulated process.
00245  */
00246 pid_t rk_stub_mk_pid(const char *name,
00247                      void *data,
00248                      rk_stub_precall_t precall,
00249                      rk_stub_postcall_t postcall);
00250 
00251 /**
00252  * Get the CPU usage for the simulated process.
00253  *
00254  * @param pid The process(es) to query for usage information.
00255  * @param ru The rusage object to fill out.
00256  * @return Zero if the query was successful, otherwise it returns -1 and sets
00257  *         errno appropriately.
00258  */
00259 void rk_stub_getrusage(pid_t pid, struct rusage *ru);
00260 
00261 enum {
00262     SDB_IN_TICK,
00263 };
00264 
00265 /*
00266  * Flags for struct rk_stub_data.
00267  *
00268  * SDF_IN_TICK - Indicates that the simulator is currently processing ticks.
00269  */
00270 enum {
00271     SDF_IN_TICK = (1L << SDB_IN_TICK),
00272 };
00273 
00274 /**
00275  * The maximum number of simulated process control blocks.
00276  */
00277 #define MAX_PCB 128
00278 
00279 /*
00280  * The rk_stub_data structure holds any global data for the stub code.
00281  *
00282  * sd_Flags - The holder for the above SDF_ flags.
00283  * sd_Mode - The current operating mode.
00284  * sd_LogFile - The stub log file.
00285  * sd_ResourceSets - The list of active resource sets.
00286  * sd_CurrentTime - The current simulated time.
00287  * sd_NextTime - The simulated time of the next event.
00288  * sd_PCBs - Statically allocated rk_stub_pcb objects.
00289  */
00290 struct rk_stub_data {
00291     unsigned long sd_Flags;
00292     rk_stub_mode_t sd_Mode;
00293     FILE *sd_LogFile;
00294     struct lnMinList sd_ResourceSets;
00295     struct timespec sd_CurrentTime;
00296     struct timespec sd_NextTime;
00297     struct rk_stub_pcb sd_PCBs[MAX_PCB];
00298 };
00299 
00300 #ifdef __cplusplus
00301 }
00302 #endif
00303 
00304 #endif

Generated on Mon Dec 1 16:29:07 2003 for CPU Broker by doxygen 1.3.4