rk_stub.h

Go to the documentation of this file.

/*
 * rk_stub.h
 *
 * Copyright (c) 2003 The University of Utah and the Flux Group.
 * All rights reserved.
 *
 * This file is licensed under the terms of the GNU Public License.  
 * See the file "license.terms" for restrictions on redistribution 
 * of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 */

/**
 * @file rk_stub.h
 *
 * The simulator specific structures and function.
 *
 * @sa rk.h
 */

#ifndef _rk_stub_h
#define _rk_stub_h

#include <stdio.h>

#include <sys/types.h>
#include <sys/time.h>
#include <sys/resource.h>

#include <listNode.h>

#include "rk.h"

#ifdef __cplusplus
extern "C" {
#endif

/**
 * Forward declaration of the CPU reservation structure.
 */
typedef struct cpu_reserve *cpu_reserve_t;

/*
 * The rk_resource_set is the root structure for resource allocations.
 *
 * rs_Link - Linked list node.
 * rs_Name - Statically allocated memory for the set name.
 * rs_ProcessID - The simulated pid_t this set is attached too.
 * rs_CPU - The CPU reservation for this set.
 */
struct rk_resource_set {
    struct lnMinNode rs_Link;
    char rs_Name[RSET_NAME_LEN];
    pid_t rs_ProcessID;
    cpu_reserve_t rs_CPU;
};

/**
 * The rk_cpu_reserve_trace_t type enumerates the set of trace files generated
 * by the stubs.
 *
 * @e NOTE: Update rk_cpu_trace_names in the source file if you make any
 * changes.
 */
typedef enum {
    RK_CPU_TRACE_PERIOD,        /**< Process period. */
    RK_CPU_TRACE_DEADLINE,      /**< Process deadline, relative to the period.
                                 */
    RK_CPU_TRACE_COMPLETE,      /**< Completion of data processing. */
    RK_CPU_TRACE_DROP,          /**< Data dropped before processing. */
    RK_CPU_TRACE_REALTIME,      /**< Exact CPU time required to meet the
                                     deadline. */
    RK_CPU_TRACE_COMPUTE_SUCCESS,       /**< Actual CPU time, for successful
                                             periods. */
    RK_CPU_TRACE_COMPUTE_FAIL,  /**<  Actual CPU time, for failed periods. */
    RK_CPU_TRACE_MAX
} rk_cpu_reserve_trace_t;

enum {
    CRB_RUNNING,
};

/*
 * Flags for struct cpu_reserve.
 *
 * CRF_RUNNING - Indicates whether or not the process is currently running on
 *               the CPU.
 */
enum {
    CRF_RUNNING = (1L << CRB_RUNNING),
};

/*
 * The cpu_reserve is used to trace CPU usage for a resource set.  The majority
 * of the data structure is devoted to tracking the CPU time periods and the
 * data progress periods.  Basically, we need to know not only when the
 * scheduler will give the process CPU time, but also whether or not it is
 * processing its data on time.  For example, if the process was not given
 * enough compute_time and is taking 50% longer to process the inputs its data
 * periods will not match the CPU periods.
 *
 * CPU   |---|  |---|  |---|  |---|   where:   | -> Period begin/end
 * DATA  |---+  +-|-+  +---|  |---+            + -> Period continued
 *
 * cr_Attributes - The current reservation spec.
 * cr_Flags - The holder for the above CRF_* flags.
 * cr_Compute.cr_Times - The CPU times required to meet the deadline for a
 *                       given period.  The times are looped so accesses must
 *                       be modded with the length.
 * cr_Compute.cr_Length - The number of elements in cr_Times.
 * cr_Compute.cr_DataIndex - The current data set being processed.  In other
 *                           words, the task has processed this many data
 *                           inputs.
 * cr_Compute.cr_TimeIndex - The current period index.  In other words, the
 *                           task has been scheduled and run for this many
 *                           periods.
 * cr_Compute.cr_DataPeriodStart - The start of the current data processing
 *                                 period.
 * cr_Compute.cr_DataPeriodEnd - The end of the current data processing period.
 * cr_Compute.cr_DataPeriodNext - The start of the next data processing period.
 * cr_Compute.cr_DataPeriodRemaining - The amount of processing left in the
 *                                     data period.
 * cr_Compute.cr_TimePeriodStart - The start of the current CPU period.
 * cr_Compute.cr_TimePeriodEnd - The end of the current CPU period.
 * cr_Compute.cr_TimePeriodNext - The start of the next CPU period.
 * cr_Trace - The trace files as enumerated above.
 */
struct cpu_reserve {
    struct cpu_reserve_attr cr_Attributes;
    
    unsigned long cr_Flags;
    struct {
        struct timespec *cr_Times;
        unsigned int cr_Length;
        unsigned int cr_DataIndex;
        unsigned int cr_TimeIndex;
        
        struct timespec cr_DataPeriodStart; // Inclusive
        struct timespec cr_DataPeriodEnd; // Exclusive
        struct timespec cr_DataPeriodNext; // Inclusive
        struct timespec cr_DataPeriodRemaining; // Length
        
        struct timespec cr_TimePeriodStart; // Inclusive
        struct timespec cr_TimePeriodEnd; // Exclusive
        struct timespec cr_TimePeriodNext; // Inclusive
    } cr_Compute;
    FILE *cr_Trace[RK_CPU_TRACE_MAX];
};

enum {
    PCBB_IN_USE,
};

/*
 * Flags for rk_stub_pcb.
 *
 * PCBF_IN_USE - Indicates that the rk_stub_pcb object has been allocated.
 */
enum {
    PCBF_IN_USE = (1L << PCBB_IN_USE),
};

/**
 * The rk_stub_precall_retval_t type enumerates the possible return values for
 * an rk_stub_precall_t call back.
 */
typedef enum {
    RKSP_OK,    /**< Simulation of the data period should continue as normal */
    RKSP_DROP,  /**< The data has been dropped, move to the next period. */
} rk_stub_precall_retval_t;

/**
 * Prototype for the pre-data-period process call back.  These functions are
 * called before a new data period is simulated.
 *
 * @param data The process specific data.
 * @return An rk_stub_precall_retval_t value.
 */
typedef rk_stub_precall_retval_t (*rk_stub_precall_t)(void *data);

/**
 * Prototype for the post-data-period process call back.  These functions are
 * called after a data period has been simulated.
 *
 * @param data The process specific data.
 */
typedef void (*rk_stub_postcall_t)(void *data);

/*
 * The rk_stub_pcb stores any information needed for simulated processes.
 *
 * p_Name - The name of the process.
 * p_Flags - The holder for the above PCBF_* flags.
 * p_Data - Refers to any process specific data.
 * p_Precall - Function pointer that gets called before a data period begins,
 *             the argument is the value in p_Data.
 * p_Postcall - Function pointer that gets called after a data period ends,
 *              the argument is the value in p_Data.
 * p_Resources - The resource allocation for this process.
 */
struct rk_stub_pcb {
    const char *p_Name;
    unsigned long p_Flags;
    void *p_Data;
    struct rusage p_Usage;
    rk_stub_precall_t p_Precall;
    rk_stub_postcall_t p_Postcall;
    rk_resource_set_t p_Resources;
};

/**
 * The rk_stub_mode_t type enumerates the set of modes the rk_stub code can
 * support.
 */
typedef enum rk_stub_mode_t {
    RK_STUB_MIN,
    RK_STUB_LOG,        /**< Log all rk_* function calls. */
    RK_STUB_SIM,        /**< Same as RK_STUB_LOG, plus the simulator. */
    RK_STUB_MAX
} rk_stub_mode_t;

/**
 * Initialize the stub code and set the desired mode.
 *
 * @param mode One of the values in rk_stub_mode_t.
 */
void rk_stub_set_mode(rk_stub_mode_t mode);

/**
 * Advance the simulated time.  Simulated time starts at zero and then
 * continually advances to the next simulated event, such as a period end.
 */
void rk_stub_next_tick(void);

/**
 * Make a simulated process that will "consume" resources during its period.
 *
 * @sa rk_resource_set_attach_process
 * @sa rk_resource_set_detach_process
 *
 * @param name The name of the process.
 * @param data Process specific data, if any.
 * @param precall Function to call before a data period begins, can be NUL.
 * @param postcall Function to call after a data period ends, can be NULL.
 * @return The pid_t for the simulated process.
 */
pid_t rk_stub_mk_pid(const char *name,
                     void *data,
                     rk_stub_precall_t precall,
                     rk_stub_postcall_t postcall);

/**
 * Get the CPU usage for the simulated process.
 *
 * @param pid The process(es) to query for usage information.
 * @param ru The rusage object to fill out.
 * @return Zero if the query was successful, otherwise it returns -1 and sets
 *         errno appropriately.
 */
void rk_stub_getrusage(pid_t pid, struct rusage *ru);

enum {
    SDB_IN_TICK,
};

/*
 * Flags for struct rk_stub_data.
 *
 * SDF_IN_TICK - Indicates that the simulator is currently processing ticks.
 */
enum {
    SDF_IN_TICK = (1L << SDB_IN_TICK),
};

/**
 * The maximum number of simulated process control blocks.
 */
#define MAX_PCB 128

/*
 * The rk_stub_data structure holds any global data for the stub code.
 *
 * sd_Flags - The holder for the above SDF_ flags.
 * sd_Mode - The current operating mode.
 * sd_LogFile - The stub log file.
 * sd_ResourceSets - The list of active resource sets.
 * sd_CurrentTime - The current simulated time.
 * sd_NextTime - The simulated time of the next event.
 * sd_PCBs - Statically allocated rk_stub_pcb objects.
 */
struct rk_stub_data {
    unsigned long sd_Flags;
    rk_stub_mode_t sd_Mode;
    FILE *sd_LogFile;
    struct lnMinList sd_ResourceSets;
    struct timespec sd_CurrentTime;
    struct timespec sd_NextTime;
    struct rk_stub_pcb sd_PCBs[MAX_PCB];
};

#ifdef __cplusplus
}
#endif

#endif

---