trace.h

Go to the documentation of this file.

/** @file trace.h
 * Contains all the userspace and kernel space macros for running
 * TRACE.  It also contains some of the data structures, and the 
 * userspace initialization routine.
 */

#ifndef __TRACE_H
#define __TRACE_H

/*  This file (trace.h) was created by Ron Rechenmacher <ron@fnal.gov> on
    Dec 20, 1999. "TERMS AND CONDITIONS" governing this file are in the README
    or COPYING file. If you do not have such a file, one can be obtained by
    contacting Ron or Fermi Lab in Batavia IL, 60510, phone: 630-840-3000.
*/
#define __TRACE_H_REV   "\
$RCSfile: trace.h,v $\
$Revision: 1.1.1.1 $\
$Date: 2009/10/09 20:03:00 $"

#ifdef __KERNEL__
# include <linux/types.h>       /* pid_t */
#else
# include <sys/types.h>         /* pid_t, open */
# include <sys/stat.h>          /* open */
# include <stdio.h>             /* perror */
# include <fcntl.h>             /* open */
# include <unistd.h>            /* mmap */
# include <sys/mman.h>          /* mmap */
# include <sys/ioctl.h>         /* ioctl */
# include <string.h>            /* strlen */
# ifdef __USE_POSIX
#  include <time.h>             /* localtime_r */
# else
#  define __USE_POSIX
#  include <time.h>             /* localtime_r */
#  undef __USE_POSIX
# endif
# include <sys/time.h>          /* NESTED by time.h struct timeval */
# include <stdarg.h>            /* varargs */
# include <stdio.h>             /* printf */
# include <rms/util/trace_intr.h>       /* *** THE APPROPRIATE trace_function! *** */
# include <stdlib.h>            /* malloc */
# include <alloca.h>            /* alloca */
#endif

/**
 * The TRACE macro
 *
 * The macro first checks to see if TRACE is installed on the system. This is 
 * accomplished by the TRACE_INIT_CHECK macro. If TRACE is in fact installed 
 * we move on and verify that logging with TRACE is enabled, and that logging 
 * as the appropriate level is enabled. If all that is true, we call the 
 * TRACE_FUNCTION. The TRACE macro will return the time at which it was called. 
 * If no TRACE took place, the time will be 0.
 *
 * @bug The TRACE_USER_FUNCTION macro should be taken out.  The TRACE_FUNCTION
 * macro should handle printing to all the TRACE functions.  
 *
 * @param lvl The TRACE level
 * @param msg The TRACE format message
 * @param params Parameters for the TRACE format message
 *
 * @return The time that the macro was called if TRACE is setup on the system,
 * 0 otherwise.
 */

#define TRACE( lvl, msg, params... ) \
({      int             lidx;\
        struct timeval  lclTime={0,0};/*an indication that no trace occurred*/\
    /* first function activated sets the reference time */\
    TRACE_INIT_CHECK;\
    lidx = TRACE_TID * traceControl_sp->numberOfFunctions;\
    if ((traceControl_sp->mode&(1<<0)) && (traceLevel_ip[lidx+0]&(1<<lvl)))\
    {   /* need to provide a way to return time (only when in user space\
           though?maybe?) */\
        TRACE_FUNCTION( &lclTime, TRACE_TID, lvl, msg , ## params );\
    }\
    TRACE_USER_FUNCTION( &lclTime, TRACE_TID, lvl, msg , ## params );\
    lclTime;\
})

/**
 * The maximum number of TRACE message logging functions that can be
 * used.  The TRACE mode is a bitmask for enabling the different TRACE
 * functions.  Because the TRACE mode is an integer, we are limited
 * to however many bit are in an integer.
 */ 
#define TRACE_MAXIMUM_NUMBER_OF_FUNCTIONS       (sizeof(int)*8)

/**
 * The default name for a TRACE source 
 */
# ifndef TRACE_NAME
#  define TRACE_NAME ""
# endif

/**
 * Determine the difference in microseconds between two 
 * timeval structures.
 *
 * @param sooner The earlier timeval struct
 * @param later The later timeval struct
 *
 * @return The difference in microseconds between the two
 * timeval structures.
 */
#define traceControl_TimeDiff( sooner, later )  \
                                ({  int secs, usecs;\
                                    secs  = later.tv_sec - sooner.tv_sec;\
                                    usecs = later.tv_usec - sooner.tv_usec;\
                                    ((secs*1000000) + usecs);\
                                })


#if __GNUC_MINOR__ == 96 || __GNUC__ == 3
# define TRACE_COMPILER_DOES_DYNAMIC_ARRAYS 0
#else
# define TRACE_COMPILER_DOES_DYNAMIC_ARRAYS 1
#endif

/**
 * The maximum number of integer parameters that can be passed
 * to the TRACE macro.
 */
#define TRACE_NUM_PARAMETER_INTS        6

/**
 * This structure groups information about the headings and spacing
 * of elements as they are printed out of the TRACE circular buffer.
 */
struct  s_tracePrint
{   
  char *heading; /**< The heading, or field name */
  int width; /**< The width of the field, in characters */
  char type; /**< The field type, d for integer, L for long, and 0 for string */
  int offset; /**< The place in the field that the least significant digit will be printed */
};

/**
 * Contains all the settings and pointers to all the relevant TRACE 
 * data structures.
 */
struct s_traceControl
{   
  char blockMarker[28]; /**< Filled with "beginning of trace control structure".
                         * Used to mark the beginning of the TRACE control data
                         * structure. */

  int numberOfTID; /**< The maximum number of TRACE IDs allowable */
  int nameSize_bytes; /**< The maximum length of a TRACE ID's name, in bytes */
  int numberOfFunctions; /**< The number of TRACE logging functions running */
  int circularQueueSize_bytes; /**< The size of the TRACE circular queue in bytes,
                                * which is configurable at startup. */
  int messageSize_bytes; /**< The maximum length of the TRACE format message */
  int numberOfParameter_integers; /**< The maximum number of integer parameters
                                   * that can be used with the TRACE message */
  
  struct s_tracePrint *print_sp; /**< A pointer to a data structure containing all
                                  * the headings for printing the TRACE buffer */
  int printAscending; /**< I don't know, this isn't used anywhere. */
  int printHeading; /**< Determines whether or not the heading is printed when looking
                     * at the TRACE circular buffer. */
  int mode; /**< The TRACE mode, a bit mask used to determine which TRACE functions
             * are enabled. */
  int initializationOK; /**< This is set to 0 until the trace_init() routine has completed. */
  
  int *initialLevel; /**< Pointer to an array of integers that contains the initial levels
                      * for all the TRACE functions. */
  
  char *name_a; /**< Pointer to an array of chars that has all the TRACE ID's names */
  
  int circularQueueEntrySize_bytes; /**< The size in bytes of an entry in the TRACE circular
                                     * queue. This will changed depending on the size of the
                                     * format string and the number of parameters. */
  int circularQueueEntries; /**< The total number of entries that the circular queue can hold */
  char *circularQueueFirst; /**< Pointer to the first byte of first entry */
  char *circularQueueLast; /**< Pointer to the first byte of last entry */
  char *circularQueueHead; /**< Pointer to the first byte of the entry that is the head of the queue. */
  char *circularQueueTail; /**< Pointer to the first byte of the entry that is the tail of the queue. */
  int circularQueueFull; /**< Shows whether or not the queue is full. */
  int circularQueueEntriesUsed; /**< Keeps track of the number of entries that are in use in the queue. */
};

/**
 * Enumerations for the various things you can have TRACE do through the ioctl()
 * interface.
 */
enum e_traceIoctl
{   traceIoctl_e_init,
    traceIoctl_e_mapControl,
    traceIoctl_e_mapLevel,
    traceIoctl_e_reset,
    traceIoctl_e_versionGet,
    traceIoctl_e_cpuGet,
    traceIoctl_e_modeSet,
    traceIoctl_e_levelSet,
    traceIoctl_e_PMCGet
};

/** 
 * Used to pass information between user space and kernel space
 * through the ioctl() mechanism.
 */
union u_traceIoctl
{   struct
    {   int                     num;
        void                    *ptr;
        int                     mask;  /* mask will also contain cpuid for PMC Get/Read */
    } generic;
    struct
    {   unsigned long long      pmc_data_val;
        int                     whichIn_cpuidOut;
    } pmc;
};

#ifdef __KERNEL__

# include <linux/time.h>        /* do_gettimeofday */
# include <linux/version.h>      /* LINUX_VERSION_CODE, KERNEL_VERSION */
# if LINUX_VERSION_CODE >= KERNEL_VERSION(2,6,0)
# include <asm/system.h>        
# include <linux/trace_sys.h>   /* traceCircularQueuePut, struct s_traceEntry */
# endif
extern struct s_traceControl    *traceControl_sp;
extern int                      *traceLevel_ip;
extern int                       tracePMC[];

struct s_traceEntry *
traceCircularQueuePut( int, ... );

/**
 * Inside the kernel, we don't need to run TRACE_INIT_CHECK because
 * this is done at startup, and its not really possible to create
 * messages before startup. 
 */
# define TRACE_INIT_CHECK

/**
 * The kernel TRACE ID is 0.
 */
# define TRACE_TID 0

/**
 * Since we are in fact in kernel space, we don't have to trap or
 * int to get to the TRACE function.  We can simply call the 
 * appropriate functions right away.
 *
 * @param tv_adr Pointer to a timeval struct that will contain the
 * time at which the TRACE was made.
 * @param tid The TRACE ID, usually 0 in kernel space
 * @param msg The TRACE format string
 * @param params The integer parameters to the format string
 */
# define TRACE_FUNCTION( tv_adr, tid, lvl, msg, params...) \
         do\
         {   unsigned long      __flags__;\
             struct s_traceEntry *traceEntry_sp;\
             local_save_flags( __flags__ );\
             local_irq_disable();\
             traceEntry_sp = traceCircularQueuePut( tid, lvl, msg , ## params );\
             *tv_adr = traceEntry_sp->time;\
             local_irq_restore( __flags__ );\
         } while (0)


# ifndef  TRACE_USER_FUNCTION
extern  void    (*(*trace_kernel_functions)[])( struct timeval*, int, int, char*, ... ); /* ptr to array of function ptrs */

/**
 * The TRACE_USER_FUNCTION macro is responsible for iterating through all the TRACE
 * functions and calling them with the appropriate parameters.
 *
 * @bug Why do we check to see if TRACE is on and the message has an appropriate
 * level in the TRACE macro _AND_ this macro?
 *
 * @param tv_adr Pointer to a timeval struct that will contain the
 * time at which the TRACE was made.
 * @param tid The TRACE ID, usually 0 in kernel space
 * @param msg The TRACE format string
 * @param params The integer parameters to the format string
 */ 
#  define TRACE_USER_FUNCTION( tv_adr, tid, lvl, msg, params... ) \
    /* NOTE THE FUNCTION ARRAY IDX 0 LINES UP WITH MODE/LEVEL IDX 1 */\
    do \
    {       int _ii_, lidx;\
        lidx = TRACE_TID * traceControl_sp->numberOfFunctions;\
        for (_ii_=1; _ii_<traceControl_sp->numberOfFunctions; _ii_++)\
        {   if ((traceControl_sp->mode&(1<<_ii_)) && (traceLevel_ip[lidx+_ii_]&(1<<lvl)))\
            {\
              if ((*trace_kernel_functions)[_ii_-1])\
              {   char _tmp_buf_[traceControl_sp->messageSize_bytes+4];\
                  int _jj_;\
                  if ((tv_adr)->tv_sec == 0) do_gettimeofday( tv_adr );\
                  for (_jj_=0; (_jj_<traceControl_sp->messageSize_bytes) && *((msg)+_jj_); _jj_++)\
                  {   _tmp_buf_[_jj_] = *((msg)+_jj_);\
                  }\
                  _tmp_buf_[_jj_] = '\n'; _jj_++;\
                  _tmp_buf_[_jj_] = '\0';\
                  (*trace_kernel_functions)[_ii_-1]( tv_adr, tid, lvl, _tmp_buf_ , ## params );\
              }\
            }\
        }\
    } while (0)
# endif

/**
 * the traceControl_Mode() macro changes the TRACE mode.  The
 * mode is a bit mask that determines which TRACE functions are
 * enabled.
 *
 * @param new_mode The new mode TRACE will be in.
 *
 * @return The mode TRACE was in.
 */
#define traceControl_Mode( new_mode )   \
                        ({  int old_mode;\
                            old_mode = traceControl_sp->mode;\
                            traceControl_sp->mode = new_mode;\
                            old_mode;\
                        })

/**
 * Macro to get the current TRACE mode.  The mode is a bit mask
 * that determines which TRACE functions are enabled.
 *
 * @return The current TRACE mode
 */
#define traceControl_ModeGet()  \
                        ({  traceControl_sp->mode;\
                        })


#else   /* USER SPACE  -------------------------------------------------------*/

/**
 * Global pointer to the TRACE control structure.
 */
static struct s_traceControl    *traceControl_sp=0;

/** 
 * Pointer to an array that contains the information
 * about the levels for all the TRACE functions.
 *
 * @bug Why is this not in the traceControl data structure?
 */
static int                      *traceLevel_ip;

/**
 * Global value to keep track of the TRACE ID of the current
 * process.
 */
static int                      traceTID=0;

/**
 * Check to see if the kernel has TRACE support, and if so
 * map the traceControl data strcture into our address space
 * so we can do stuff with it.
 */                                      
# define TRACE_INIT_CHECK       do\
                                { if (!traceControl_sp)traceControl_Init("");\
                                } while (0)

/**
 * The numerical TRACE ID.  This is procured from the TRACE_NAME.
 */
# define TRACE_TID              traceTID

/**
 * The TRACE_FUNCTION sets the appropriate registers and then
 * jumps into kernel space.  There is a seperate TRACE_FUNCTION
 * for each architecture that TRACE supports.
 *
 * @param tv_adr Pointer to a timeval struct that will contain the
 * time at which the TRACE was made.
 * @param tid The TRACE ID, usually 0 in kernel space
 * @param msg The TRACE format string
 * @param params The integer parameters to the format string
 */
# define TRACE_FUNCTION( tv_adr, tid, lvl, msg, params... ) \
                                trace_function( tv_adr, tid\
                                               ,lvl, msg , ## params )

#ifndef  TRACE_FUNCTIONS
/**
 * An array of function pointers to the various userspace TRACE
 * functions.  They can be used as follows:
 *
 *  extern void trace_print( struct timeval, int, int, char*, ...);
 *  #define TRACE_FUNCTIONS {trace_print}
 *  #define TRACE_NAME "simple"
 */
#define TRACE_FUNCTIONS {0,0,trace_printf}

/**
 * A user space TRACE print function.  This one prints TRACE messages
 * using printf.
 *
 * @param tv_adr Pointer to a timeval struct that will contain the
 * time at which the TRACE was made.
 * @param tid The TRACE ID, usually 0 in kernel space
 * @param msg The TRACE format string
 * @param params The integer parameters to the format string
 */

static void trace_printf( struct timeval *tv_sp, int tid, int lvl, char *msg, ... )
{       va_list         ap;
        char            timbuf[100];
        int             timlen;
        char            *newbuf;
        struct tm       tm_s;

    localtime_r( (time_t *)&tv_sp->tv_sec, &tm_s );
    timlen = strftime( timbuf, sizeof(timbuf), "%a %H:%M:%S", &tm_s );

    sprintf( &timbuf[timlen], ".%06d: ", (int)tv_sp->tv_usec );
    newbuf = (char *)alloca( timlen+strlen(&timbuf[timlen])+strlen(msg)+2/*room for "\n\0"*/ );

    /* now accomplish the prepending of the time and the appending of the newline */
    sprintf( newbuf, "%s%s\n", timbuf, msg );

    va_start( ap, msg );
    vprintf( newbuf, ap );
    va_end( ap );

    return;
}

# endif
# ifndef  TRACE_USER_FUNCTION
typedef void (*func_ptr_t)(struct timeval*,int,int,char*,...);
static func_ptr_t trace_user_functions[]=TRACE_FUNCTIONS;

/**
 * The TRACE_USER_FUNCTION macro loops through all the user space
 * TRACE functions and executes them.
 *
 * @param tv_adr Pointer to a timeval struct that will contain the
 * time at which the TRACE was made.
 * @param tid The TRACE ID, usually 0 in kernel space
 * @param msg The TRACE format string
 * @param params The integer parameters to the format string
 */

#  define TRACE_USER_FUNCTION( tv_adr, tid, lvl, msg, params... ) \
    /* NOTE THE FUNCTION ARRAY IDX 0 LINES UP WITH MODE/LEVEL IDX 1 */\
    do \
    {       int _ii_, lidx;\
        lidx = TRACE_TID * traceControl_sp->numberOfFunctions;\
        for (_ii_=1; _ii_<traceControl_sp->numberOfFunctions; _ii_++)\
        {   if ((traceControl_sp->mode&(1<<_ii_)) && (traceLevel_ip[lidx+_ii_]&(1<<lvl)))\
            { if (trace_user_functions[_ii_-1])\
              {   if ((tv_adr)->tv_sec == 0) gettimeofday( tv_adr, 0 );\
                  trace_user_functions[_ii_-1](tv_adr,tid,lvl, msg , ## params );\
              }\
            }\
        }\
    } while (0)
# endif

/**
 * traceControl_fd is point at /proc/trace/control and is used when
 * making ioctl() calls for TRACE.
 */
static int                      traceControl_fd=0;

/**
 * This is the level mask that is used if TRACE is disabled.
 *
 * @bug Should this be 4, or should it be the number of TRACE
 * functions?
 */
static int                      disabled_level[4]={0};

/**
 * This is a copy of the control structure that has been disabled
 * and is used when there is no TRACE support in the kernel.
 */
static struct s_traceControl    disabled_control={{0}};

/**
 * Called if there is TRACE support in the kernel, this function
 * will initialize the traceControl_sp data structures.
 *
 * @param name The TRACE name that will be used for all logging.
 */
static int traceControl_Init( char *name )
{
        int                     fd_map;
        int                     levelArraySize;
        int                     levelOffset;
        int                     sts;
        union u_traceIoctl      ioctl_data;

    /*  This should assure we do init processing once. Use ReInit to
        change name.
        Note: first call may return -1 while successive calls will
        return 0. */
    if (traceControl_sp) return (0);

    /* incase anything bad happens... */
    traceTID = 0;
    traceControl_sp = &disabled_control;
    traceLevel_ip   = disabled_level;
    traceControl_sp->numberOfFunctions = ( sizeof(disabled_level)
                                          /sizeof(disabled_level[0]));

    traceControl_fd = open( "/proc/trace/control", O_RDONLY );
    if (traceControl_fd == -1)
    {   perror( "open /proc/trace/control" );
        fprintf( stderr, "continueing with disabled tracing\n" );
        return (-1);
    }

    /* get a traceTID via ioctl */
    if (name[0] == '\0')
    {   /* try TRACE_NAME (which may actually be the same thing [""] */
        name = TRACE_NAME;
    }
    ioctl_data.generic.ptr = name;
    sts = ioctl( traceControl_fd, traceIoctl_e_init, &ioctl_data );
    traceTID = ioctl_data.generic.num;


    fd_map = open( "/proc/trace/map", O_RDONLY );
    if (fd_map == -1)
    {   perror( "open /proc/trace/map" );
        fprintf( stderr, "continueing with disabled tracing\n" );
        traceTID = 0;
        traceControl_fd = -1;
        traceControl_sp = &disabled_control;
        traceLevel_ip   = disabled_level;
        traceControl_sp->numberOfFunctions = ( sizeof(disabled_level)
                                              /sizeof(disabled_level[0]));
        return (-1);
    }

    traceControl_sp = (struct s_traceControl *)mmap(  0 /* hint address */
                                                    , sizeof(struct s_traceControl)
                                                    , PROT_READ
                                                    , MAP_SHARED
                                                    , fd_map
                                                    , 0 /* offset */ );
    if (traceControl_sp == (void *)-1/*MAP_FAILED*/)
    {   perror( "mmap /proc/trace/map" );
        fprintf( stderr, "continueing with disabled tracing\n" );
        traceTID = 0;
        traceControl_fd = -1;
        traceControl_sp = &disabled_control;
        traceLevel_ip   = disabled_level;
        traceControl_sp->numberOfFunctions = ( sizeof(disabled_level)
                                              /sizeof(disabled_level[0]));
        return (-1);
    }

    levelArraySize = ( traceControl_sp->numberOfTID
                      *traceControl_sp->numberOfFunctions);

    /*  NEED TO REORGANIZE STRUCTURE TO REMOVE HARD CODED NUMBER
        ref. trace_proc.c:trace_proc_map_mmap() */
    levelOffset = 4096;

    traceLevel_ip = (int *)mmap(  0 /* hint address */
                                , levelArraySize * sizeof(int)
                                , PROT_READ
                                , MAP_SHARED
                                , fd_map
                                , levelOffset );

    if (traceLevel_ip == (void *)-1/*MAP_FAILED*/)
    {   perror( "mmap level" );
        fprintf( stderr, "continueing with disabled tracing\n" );
        traceTID = 0;
        traceControl_fd = -1;
        traceControl_sp = &disabled_control;
        traceLevel_ip   = disabled_level;
        traceControl_sp->numberOfFunctions = ( sizeof(disabled_level)
                                              /sizeof(disabled_level[0]));
        return (-1);
    }

    /*  skip past initial
        NOTE: it does not work to add this to the offset as mmap page
        aligns the returned pointer */
    traceLevel_ip += traceControl_sp->numberOfFunctions;

    close( fd_map );

    return (0);
}   /* traceControl_Init */

/**
 * Get a new TRACE ID and name for a process. This can be useful
 * for forked processes that want a different name.
 *
 * @param name The new TRACE name
 */
#define traceControl_ReInit( name )     \
                        ({  int __sts__=0;\
                            if (!traceControl_sp)\
                            {   traceControl_Init("");\
                            }\
                            else if (traceControl_fd > 0)\
                            {   /* get a traceTID via ioctl */\
                                union u_traceIoctl      ioctl_data;\
                                ioctl_data.generic.ptr = name;\
                                __sts__ = ioctl( traceControl_fd, traceIoctl_e_init, &ioctl_data );\
                                traceTID = ioctl_data.generic.num;\
                            }\
                            __sts__;\
                        })

/**
 * Set the TRACE mode.  Currently, there are two modes.  Mode "0"
 * is TRACE turned off, while mode "1" is TRACE turned on.
 *
 * @param new_mode The mode that TRACE will switch to.
 */
#define traceControl_Mode( new_mode )   \
                        ({  int old_mode;\
                            if (!traceControl_sp) traceControl_Init("");\
                            old_mode = traceControl_sp->mode;\
                            if (traceControl_fd > 0)\
                            {   ioctl( traceControl_fd, traceIoctl_e_modeSet, new_mode );\
                            }\
                            old_mode;\
                        })

/**
 * Get the current TRACE mode.
 *
 * @return The current TRACE mode.
 */
#define traceControl_ModeGet()  \
                        ({  if (!traceControl_sp) traceControl_Init("");\
                            traceControl_sp->mode;\
                        })

/**
 * Apply a mask (bitwise OR) to the TRACE mode.
 *
 * @param mask The mask that will be ORed with the TRACE mode.
 */ 
#define traceControl_ModeSet( mask )    \
                        ({  int old_mode, new_mode;\
                            if (!traceControl_sp) traceControl_Init("");\
                            old_mode = traceControl_sp->mode;\
                            new_mode = old_mode | mask;\
                            if (traceControl_fd > 0)\
                            {   ioctl( traceControl_fd, traceIoctl_e_modeSet, new_mode );\
                            }\
                            else\
                            {   traceControl_sp->mode = new_mode;\
                            }\
                            old_mode;\
                        })

/**
 * Apply a mask (bitwise AND) to the TRACE mode.
 *
 * @param mask The mask that will be ANDed to the TRACE mode.
 */
#define traceControl_ModeClr( mask )    \
                        ({  int old_mode, new_mode;\
                            if (!traceControl_sp) traceControl_Init("");\
                            old_mode = traceControl_sp->mode;\
                            new_mode = old_mode & ~mask;\
                            if (traceControl_fd > 0)\
                            {   ioctl( traceControl_fd, traceIoctl_e_modeSet, new_mode );\
                            }\
                            else\
                            {   traceControl_sp->mode = new_mode;\
                            }\
                            old_mode;\
                        })

/**
 * Reset TRACE, which clears the TRACE circular buffer.
 */
#define traceControl_Reset()    \
                        ({  if (!traceControl_sp) traceControl_Init("");\
                            if (traceControl_fd > 0)\
                            {   ioctl( traceControl_fd, traceIoctl_e_reset, 0 );\
                            }\
                        })

/**
 * Get the data from the Performance Monitoring Counter on a specific
 * CPU.
 *
 * @param which Which CPU to get the data from
 * @return The value from the PMC on the specific CPU.
 */
#define traceControl_PMCGet( which )    \
                        ({   union u_traceIoctl ioctl_data;\
                             if (!traceControl_sp) traceControl_Init("");\
                             if (traceControl_fd > 0)\
                             {   ioctl_data.pmc.whichIn_cpuidOut = which;\
                                 ioctl( traceControl_fd, traceIoctl_e_PMCGet, &ioctl_data );\
                             }\
                             ioctl_data.pmc.pmc_data_val;\
                        })

/**
 * Practically the same as traceControl_PMCGet, except that
 * this will place the cpuID in the area pointed to by
 * cpuidOut_ptr.
 *
 * @bug I really don't know what this will do.
 *
 * @param which The processor to retreive PMC data from
 * @param cpuidOut_ptr A pointer to an int where the processes ID will be stored.
 */
#define traceControl_PMCRead( which, cpuidOut_ptr )     \
                        ({   union u_traceIoctl ioctl_data;\
                             if (!traceControl_sp) traceControl_Init("");\
                             if (traceControl_fd > 0)\
                             {   ioctl_data.pmc.whichIn_cpuidOut = which;\
                                 ioctl( traceControl_fd, traceIoctl_e_PMCGet, &ioctl_data );\
                             }\
                             *(cpuidOut_ptr) = ioctl_data.pmc.whichIn_cpuidOut;\
                             ioctl_data.pmc.pmc_data_val;\
                        })

/**
 * Set the TRACE level for the current TRACE ID for a particular
 * TRACE function.
 *
 * @bug Does this really want the function number? 
 * @bug __mask__ isn't a very good name.
 *
 * @param func The index of the function who's level we want to set
 * @param __mask__ The new level mask.
 */
#define traceControl_LevelSet( func, __mask__ ) \
                        ({  union u_traceIoctl  ioctl_data;\
                            if (!traceControl_sp) traceControl_Init("");\
                            if (traceControl_fd > 0)\
                            {   ioctl_data.generic.num = traceTID;\
                                ioctl_data.generic.ptr = (void*)func;\
                                ioctl_data.generic.mask = __mask__;\
                                ioctl( traceControl_fd, traceIoctl_e_levelSet, &ioctl_data );\
                            }\
                            else if (func < (sizeof(disabled_level)/sizeof(int)))\
                            {   traceLevel_ip[func] = __mask__;\
                            }\
                        })

/**
 * Get the current TRACE level for a specific TRACE function.
 *
 * @param func The index of the function who's level we want to get.
 * @return The TRACE level for the TRACE function with index func.
 */
#define traceControl_LevelGet( func )   \
                        ({  int lidx;\
                            if (!traceControl_sp) traceControl_Init("");\
                            lidx = TRACE_TID * traceControl_sp->numberOfFunctions;\
                            traceLevel_ip[lidx+func];\
                        })


#endif  /* of #else for ifdef __KERNEL__ */
/*----------------------------------------------------------------------------*/

#endif  /* __TRACE_H */