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