rk.h

Go to the documentation of this file.

/*
 * rk.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.h
 *
 * This file contains a replica of the TimeSys resource control APIs.  The goal
 * is to provide a close enough approximation that the same code can be used in
 * the simulated and real worlds.  The only visible difference between the two
 * is the definition of RK_STUB, so any simulation specific code should be
 * enclosed in an "#if defined(RK_STUB)".
 *
 * @sa rk_stub.h
 */

#ifndef _rk_h
#define _rk_h

#include <sys/types.h>
#if TIME_WITH_SYS_TIME
# include <sys/time.h>
# include <time.h>
#else
# if HAVE_SYS_TIME_H
#  include <sys/time.h>
# else
#  include <time.h>
# endif
#endif

#ifdef __cplusplus
extern "C" {
#endif

/**
 * Inform the includer that this is the stub version.
 */
#define RK_STUB 1

/**
 * Maximum length for resource kernel names in general.
 */
#define RK_NAME_LEN 16

/**
 * Maximum length for resource set names.
 */
#define RSET_NAME_LEN RK_NAME_LEN

/**
 * Minimum period of periodic process
 */
#define RT_MIN_PERIOD (struct timespec){0, 20000} /* 20uS */

/**
 * Enumeration that can be used to specify which CPU a resource set can be
 * bound to.
 */
typedef enum {
    RK_ANY_CPU = -1,    /**< Use any CPU available on the system. */
} rk_processor_t;

/**
 * The resource reservation modes.
 */
typedef enum {
    RSV_HARD = 0x1,     /**< Hard reservation */
    RSV_FIRM = 0x2,     /**< Firm reservation */
    RSV_SOFT = 0x4,     /**< Soft reservation */
} rk_reserve_mode_t;

/**
 * The resource reservation parameters.
 *
 * XXX Currently, all three fields @e must contain the same RSV value.
 */
typedef struct rk_reserve_param {
    rk_reserve_mode_t sch_mode; /**< Scheduling mode */
    rk_reserve_mode_t enf_mode; /**< Enforcement mode */
    rk_reserve_mode_t rep_mode; /**< Replenishment mode */
} *rk_reserve_param_t;

/**
 * The CPU reservation parameters.
 */
typedef struct cpu_reserve_attr {
    struct timespec compute_time;
    struct timespec period;
    struct timespec deadline;
    struct timespec blocking_time;
    struct timespec start_time;
    struct rk_reserve_param reserve_type;
    rk_processor_t processor;
} *cpu_reserve_attr_t;

/**
 * Opaque reference to a resource set.
 */
typedef struct rk_resource_set *rk_resource_set_t;

/**
 * Opaque reference to a resource reserve.
 */
typedef void *rk_reserve_t;

/**
 * NULL constant value for a resource set.
 */
#define NULL_RESOURCE_SET ((rk_resource_set_t)0)

/**
 * NULL constant value for a reserve.
 */
#define NULL_RESERVE ((rk_reserve_t)0)

/**
 * @e Not implemented.
 */
void rk_inherit_mode(int dummy);

/**
 * Query the system for the list of mock resource sets.
 *
 * @param rs_inout An array that can hold atleast 'count' rk_resource_set_t
 * elements.
 * @param count The size of the 'rs_inout' array.
 * @return The actual number of elements in the 'rs_inout' array that were
 * filled in with resource set pointers.
 */
int rk_resource_sets_get_list(rk_resource_set_t *rs_inout, int count);

/**
 * @return The number of mock resource sets that are currently active.
 */
int rk_resource_sets_get_num(void);

/**
 * Construct a mock resource set with the given name.  The name has special
 * meaning in the simulator, it will be used as the base for any files that are
 * produced or read by the stub code.  For example, a file produced or read by
 * the CPU reserve will use file names of the form: @<name@>_cpu_@<file-type@>.
 *
 * @sa rk_cpu_reserve_create
 * @sa rk_cpu_reserve_trace_t
 *
 * @param name The name for the resource set.
 * @return A new rk_resource_set_t object or NULL if the creation failed.
 */
rk_resource_set_t rk_resource_set_create(const char *name);

/**
 * Destroy a resource set.
 *
 * @param rs The resource set to destroy.
 */
int rk_resource_set_destroy(rk_resource_set_t rs);

/**
 * Set the name of a resource set.  This is provided for compatibility and is
 * otherwise unwise to use since the name has meaning in the simulation code.
 *
 * @param rs The resource set to rename.
 * @param name The new name.
 * @return Zero if the name was valid, an errno value otherwise.
 */
int rk_resource_set_set_name(rk_resource_set_t rs, const char *name);

/**
 * Get the name of a resource set.
 *
 * @param rs The resource set to query.
 * @param name_out The character array, of atleast RSET_NAME_LEN length, to
 *                 fill out with the name of the resource set.
 * @return Zero if the parameters were valid, an errno value otherwise.
 */
int rk_resource_set_get_name(rk_resource_set_t rs, char *name_out);

/**
 * Get the CPU reserve from the given resource set.
 *
 * @param rs The resource set to query.
 * @return A pointer to the CPU reserve or NULL if the resource set did not
 *         have a CPU reserve attached.
 */
rk_reserve_t rk_resource_set_get_cpu_rsv(rk_resource_set_t rs);

/**
 * Attach a process to the resource set so that its callbacks will be used
 * when a data period is starting/ending.
 *
 * @e Note: The simulator only supports one process being attached at a time.
 *
 * @param rs The resource set that will be attached to the process.
 * @param pid The fake process ID to attach to the resource set.
 * @return Zero if the process was successfully attached, an errno value
 *         otherwise.
 */
int rk_resource_set_attach_process(rk_resource_set_t rs, pid_t pid);

/**
 * Detach a process from the resource set.
 *
 * @param rs The attached resource set.
 * @param pid The fake process ID to detach from the resource set.
 * @return Zero if the process was successfully detached, an errno value
 *         otherwise.
 */
int rk_resource_set_detach_process(rk_resource_set_t rs, pid_t pid);

/**
 * @param rs The resource set to query.
 * @return The number of processes attached to the given resource set.
 */
int rk_resource_set_get_num_procs(rk_resource_set_t rs);

/**
 * Query the system for the list of processes attached to the given resource
 * set.
 *
 * @e Note: The simulator only supports one process being attached at a time.
 *
 * @param rs The resource set to query for attached processes.
 * @param procs_inout An array that can hold atleast 'count' pid_t elements.
 * @param count The size of the 'procs_inout' array.
 * @return The actual number of elements in the 'procs_inout' array that were
 * filled in with pid's.
 */
int rk_resource_set_get_proclist(rk_resource_set_t rs,
                                 pid_t *procs_inout,
                                 int count);

/**
 * Get the resource set attached to the given process.
 *
 * @param pid The fake process ID to query.
 * @return The resource set that is attached to the process or NULL if none is
 *         attached.
 */
rk_resource_set_t rk_proc_get_rset(pid_t pid);

/**
 * Create a CPU reserve for the given resource set.  In order to simulate this
 * reserve, a "times" file must be available in the current directory.  The
 * contents of the file should be a whitespace separated list of floats that
 * specify the percentage of CPU time required by the process for a repeating
 * sequence of periods.  For example, the times file for a resource set named
 * "steady_50" that required 50% of the CPU at every period would be named
 * "steady_50_cpu_times" and contain only "50.0".  Another, more complex
 * example, would be a reserve that oscillated between 10% and 50% with 10%
 * steps would contain "10.0 20.0 30.0 40.0 50.0 40.0 30.0 20.0 10.0".
 *
 * The output of CPU simulation is a set of files that can be fed into gnuplot.
 * The contents of the file are two columns of numbers, a time value, and a CPU
 * percentage or an arbitrary value that marks some event.  The current list of
 * files is:
 *
 * @li @e _cpu_period The CPU reserve's period.
 * @li @e _cpu_deadline The CPU reserve's deadline.
 * @li @e _cpu_complete Marks the completion of a data period.
 * @li @e _cpu_drop Marks a data period as being dropped.
 * @li @e _cpu_realtime The CPU time required by the process.
 * @li @e _cpu_success The actual CPU time received by a process that is making
 *                     its deadlines.
 * @li @e _cpu_fail The actual CPU time received by a process that is missing
 *                  its deadlines.
 *
 * @param rs The resource set that will hold the CPU reserve.
 * @param r_out A pointer that can be set to the new CPU reserve.
 * @param ra_in The reservation parameters.
 * @return Zero if the reserve was created successfully, an errno value
 *         otherwise.
 */
int rk_cpu_reserve_create(rk_resource_set_t rs,
                          rk_reserve_t *r_out,
                          cpu_reserve_attr_t ra_in);

/**
 * Delete a CPU reserve held by a resource set.
 *
 * @param rs A resource set.
 * @return Zero on success, -1 on error.
 */
int rk_cpu_reserve_delete(rk_resource_set_t rs);

/**
 * Get the reservation parameters for a given CPU reserve.
 *
 * @param cr The CPU reserve to query.
 * @param ra_out The cpu_reserve_attr object to fill with the CPU reserve's
 *               current parameters.
 * @return Zero if the query was successful, an errno value otherwise.
 */
int rk_cpu_reserve_get_attr(rk_reserve_t cr, cpu_reserve_attr_t ra_out);

/**
 * Change a CPU reserve's scheduling parameters.
 *
 * @param rs The CPU reserve to change.
 * @param ra_in The new scheduling parameters.
 * @return Zero if the change was successful, an errno value otherwise.
 */
int rk_cpu_reserve_ctl(rk_resource_set_t rs, cpu_reserve_attr_t ra_in);

#if !defined(HAVE_CLOCKID_T)
/**
 * A clockid_t enumeration for those OS's that do not support it.
 */
typedef enum {
    CLOCK_REALTIME,
    CLOCK_VIRTUAL,
    CLOCK_PROF
} clockid_t;
#endif

/**
 * Get the simulator's virtual time.
 *
 * @param clock_id The clock type, only CLOCK_REALTIME is supported.
 * @param ts The timespec object to fill out.
 * @return Zero if the query was successful, otherwise it returns -1 and sets
 *         errno appropriately.
 */
int rk_clock_gettime(clockid_t clock_id, struct timespec *ts);

/**
 * Set the simulator's virtual time.  This function should really only be used
 * to set the time to a value _before_ the next event.
 *
 * @param clock_id The clock type, only CLOCK_REALTIME is supported.
 * @param ts The new virtual time value.
 * @return Zero if the query was successful, otherwise it returns -1 and sets
 *         errno appropriately.
 */
int rk_clock_settime(clockid_t clock_id, struct timespec *ts);

/**
 * Get the simulator's virtual clock resolution.
 *
 * @param clock_id The clock type, only CLOCK_REALTIME is supported.
 * @param ts The timespec object to fill out.
 * @return Zero if the query was successful, otherwise it returns -1 and sets
 *         errno appropriately.
 */
int rk_clock_getres(clockid_t clock_id, struct timespec *ts);

/**
 * @copydoc rk_clock_gettime
 */
#define clock_gettime(clock_id, ts) rk_clock_gettime(clock_id, ts)

/**
 * @copydoc rk_clock_settime
 */
#define clock_settime(clock_id, ts) rk_clock_settime(clock_id, ts)

/**
 * @copydoc rk_clock_getres
 */
#define clock_getres(clock_id, ts) rk_clock_getres(clock_id, ts)

#ifdef __cplusplus
}
#endif

#endif

---