instrumentation.h

Go to the documentation of this file.

/*
 * instrumentation.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.
 */

#ifndef _misc_instrumentation_h
#define _misc_instrumentation_h

/**
 * @file instrumentation.h
 *
 * Header file for instrumentation tools.  Instrumenting blocks of code or
 * expressions is done by adding a call to CB_INSTR_POINT in the configure.in
 * file and surrounding the code with a macro call.  For example, to do high
 * resolution timings of the following code:
 *
 * @code
 *   for( lpc = 0; lpc < 100; lpc++ )
 *   {
 *       ...
 *   }
 * @endcode
 *
 * You would modify the configure.in to include:
 *
 * @code
 *   CB_INSTR_POINT([my_point],
 *                  [HRTIME_INSTR],
 *                  [My instrumentation point])
 * @endcode
 *
 * Where 'my_point' is the name of the instrumentation point, HRTIME_INSTR is
 * the C macro that will record the timings, and 'My instrumentation point' is
 * the description of the point.  The result of this call will be two new
 * definitions in the config.h: 'INSTR_my_point' and 'INSTR_my_point_data'.
 * The first C macro is used to surround the code block and the second contains
 * the data used to initialize the instrumentation point structure (iPoint).
 * With these new definitions, we can modify our original code to add
 * instrumentation:
 *
 * @code
 *   #if defined(INSTR_my_point_data)
 *   static struct iPoint IP_my_point = {
 *       INSTR_my_point_data
 *   };
 *   #endif
 * ...
 *   INSTR_my_point(&IP_my_point, ({
 *       for( lpc = 0; lpc < 100; lpc++ )
 *       {
 *           ...
 *       }
 *   }));
 * @endcode
 *
 * (Notice the parentheses around the code block, these are required for things
 * to parse correctly.)
 *
 * Finally, to enable this instrumentation point, you either need to use
 * --enable-instrumentation to enable all of the points, or
 * --enable-instrumentation=my_point to enable only this point.
 *
 * @see configure.in
 * @see instrumentation_test.c
 */

#ifdef __cplusplus
extern "C" {
#endif

#include <stdio.h>
#include <sys/time.h>

/**
 * Container for low-resolution timer values.
 */
typedef unsigned long long lrtime_t;

/**
 * @return A low-resolution time stamp.  The current resolution is on the order
 * of milliseconds.
 */
static inline lrtime_t lrtime(void);

static inline lrtime_t lrtime(void)
{
    struct timeval tv;
    lrtime_t retval;
    
    gettimeofday(&tv, 0);
    retval = (lrtime_t)tv.tv_usec / (lrtime_t)(1000);
    retval += ((lrtime_t)tv.tv_sec * (lrtime_t)(1000));
    return( retval );
}

/**
 * Container for high-resolution timer values.
 */
typedef unsigned long long hrtime_t;

/**
 * @return A high-resolution time stamp.
 */
static inline hrtime_t hrtime(void);

#if defined(i386)
static inline hrtime_t hrtime(void)
{
    unsigned long long retval;
    
    __asm__ __volatile__ ("rdtsc" : "=A" (retval) );
    return( retval );
}
#else
#warning "CPU timestamp counter not available, using gettimeofday"
static inline hrtime_t hrtime(void)
{
    struct timeval tv;
    hrtime_t retval;
    
    gettimeofday(&tv, 0);
    retval = (hrtime_t)tv.tv_usec;
    retval += ((hrtime_t)tv.tv_sec * (hrtime_t)(1000 * 1000));
    return( retval );
}
#endif

enum {
    IPB_DROP_HISTORY_START,
};

/*
 * IPF_DROP_HISTORY_START - Drop data values at the start of the history
 *   instead of the tail.
 */
enum {
    IPF_DROP_HISTORY_START,
};

/*
 * ip_Name - The name of this instrumentation point.
 * ip_Description - A description of this instrumentation point, can be NULL.
 * ip_Flags - XXX
 * ip_History.data - An array that can contain atleast ip_History.length
 *   elements that should be used to record data values as they are posted.  If
 *   left NULL, the values won't be recorded and only statistics will be
 *   available.
 * ip_History.length - The maximum number of elements that can be placed in
 *   the 'data' array.
 * ip_History.start - The index where the oldest recorded value is in the
 *   'data' array.  Normally, this will be zero, unless the
 *   IPF_DROP_HISTORY_START flag is set and the 'data' array overflowed.
 * ip_History.lost - The number of data values that were not added to the
 *   'data' array because it overflowed.
 * ip_Format - The format to use when printing values.  If this is NULL, the
 *   default format, '%10.2f  ', is used.
 * ip_Count - The number of data values posted to this instrumentation point.
 * ip_Total - The sum of the data values posted.
 * ip_Minimum - The minimum observed data value that has been posted.
 * ip_Maximum - The maximum observed data value that has been posted.
 * ip_Succ - Link to the next instrumentation point in the global linked list.
 *   Note, the instrumentation point is not added to the list until the first
 *   data value is posted.
 */
struct iPoint {
    const char *ip_Name;
    const char *ip_Description;
    unsigned long ip_Flags;
    struct {
        double *data;
        size_t length;
        unsigned int start;
        unsigned int lost;
    } ip_History;
    const char *ip_Format;
    unsigned long long ip_Count;
    double ip_Total;
    double ip_Minimum;
    double ip_Maximum;
    struct iPoint *ip_Succ;
};

/**
 * Macro used to statically initialize the ip_History field of the iPoint
 * structure.
 *
 * @param history A statically allocated array of doubles.
 */
#define IPOINT_INIT_HISTORY(history) { \
    history, \
    sizeof(history) / sizeof(double) \
}

/**
 * Macro used to perform high-resolution timings of a block of code.
 *
 * @param point The iPoint to use when recording data.
 * @param block The code block to instrument.
 *
 * @see NOINSTR
 */
#define HRTIME_INSTR(point, block) { \
    hrtime_t _start, _end; \
\
    _start = hrtime(); \
    block; \
    _end = hrtime(); \
    iPostFloatData(point, (_end - _start)); \
}

/**
 * Macro used to perform low-resolution timings of a block of code.
 *
 * @param point The iPoint to use when recording data.
 * @param block The code block to instrument.
 *
 * @see NOINSTR
 */
#define LRTIME_INSTR(point, block) { \
    lrtime_t _start, _end; \
\
    _start = lrtime(); \
    block; \
    _end = lrtime(); \
    iPostFloatData(point, (_end - _start)); \
}

/**
 * Macro used to record the value of an numeral expression.
 *
 * @param point The iPoint to use when recording data.
 * @param expr An expression that results in a number value.
 *
 * @see NOINSTR
 */
#define ACCUM_INSTR(point, expr) { \
    iPostFloatData(point, (double)(expr)); \
}

/**
 * Macro used to avoid instrumenting a block of code.
 *
 * @param point Not used.  This is only here so it can mimic the other INSTR
 * macros.
 * @param block A block of code to execute.
 *
 * @see NOINSTR
 */
#define NOINSTR(point, block) block

/*
 * The structure of global data needed by the instrumentation infrastructure.
 *
 * iid_OutputFileName - The name of the file where results should be written.
 * If NULL, a file be created with a name having the form:
 * '<PACKAGE>-instrumentation-<pid>.txt'.  If it is a '-', the results will be
 * written to standard out.
 * iid_FirstPoint - The first instrumentation point in the list.
 * iid_NullPoint - A special instrumentation point value used to detect whether
 * an iPoint object is in the global list or not.
 */
struct iInstrumentationData {
    const char *iid_OutputFileName;
    struct iPoint *iid_FirstPoint;
    struct iPoint iid_NullPoint;
};

/**
 * The global data needed by the instrumentation infrastructure.
 */
extern struct iInstrumentationData instrumentation_data;

/**
 * Post a floating point data value to an instrumentation point.
 *
 * @param ip The instrumentation point to add the given value to.
 * @param value The value to add.
 */
void iPostFloatData(struct iPoint *ip, double value);

/**
 * Print the collected values for an instrumentation point.
 *
 * @param file The file to print the data to.
 * @param ip The instrumentation point to print out.
 */
void iPrintPoint(FILE *file, struct iPoint *ip);

/**
 * Print all of the instrumentation points that have had data posted to them.
 *
 * @param file The file to print the data to.
 */
void iPrintPoints(FILE *file);

/**
 * An atexit(3) function that calls iPrintPoints with a file whose name is
 * taken from instrumentation_data.iid_OutputFileName or derived from the
 * package name and process ID.
 */
void iPrintPointsAtExit(void);

#ifdef __cplusplus
}
#endif

#endif

---