darshan.h 7.46 KB
Newer Older
1
/*
Shane Snyder's avatar
Shane Snyder committed
2 3 4
 * Copyright (C) 2015 University of Chicago.
 * See COPYRIGHT notice in top-level directory.
 *
5 6
 */

7 8 9 10 11 12
#ifndef __DARSHAN_H
#define __DARSHAN_H

#include <unistd.h>
#include <sys/types.h>
#include <stdint.h>
13 14

#ifdef HAVE_MPI
15
#include <mpi.h>
16
#endif
17

18
#include "darshan-log-format.h"
19
#include "darshan-common.h"
20

21 22 23 24
/* macros for declaring wrapper functions and calling MPI routines
 * consistently regardless of whether static or dynamic linking is used
 */
#ifdef DARSHAN_PRELOAD
Shane Snyder's avatar
Shane Snyder committed
25

26 27 28
#include <dlfcn.h>
#include <stdlib.h>

29 30
#define DARSHAN_FORWARD_DECL(__func,__ret,__args) \
  __ret (*__real_ ## __func)__args = NULL
31

32
#define DARSHAN_DECL(__func) __func
33

34 35 36
/* creates P* variant of MPI symbols for LD_PRELOAD so that we can handle
 * language bindings that map to MPI or PMPI symbols under the covers.
 */
37 38
#define DARSHAN_WRAPPER_MAP(__func,__ret,__args,__fcall) \
	__ret __func __args { \
39
		__ret i; \
40
		i = __fcall; \
41 42 43
		return i; \
	}

44 45 46 47
/* Map the desired function call to a pointer called __real_NAME at run
 * time.  Note that we fall back to looking for the same symbol with a P
 * prefix to handle MPI bindings that call directly to the PMPI layer.
 */
48 49
#define MAP_OR_FAIL(__func) \
    if (!(__real_ ## __func)) \
50
    { \
51 52
        __real_ ## __func = dlsym(RTLD_NEXT, #__func); \
        if(!(__real_ ## __func)) { \
53
            darshan_core_fprintf(stderr, "Darshan failed to map symbol: %s\n", #__func); \
54
            exit(1); \
55 56 57 58 59
       } \
    }

#else

60 61
#define DARSHAN_FORWARD_DECL(__name,__ret,__args) \
  extern __ret __real_ ## __name __args;
62 63 64

#define DARSHAN_DECL(__name) __wrap_ ## __name

65 66 67 68 69 70 71 72 73
/* creates P* variant of MPI symbols for static linking so that we can handle
 * language bindings that map to MPI or PMPI symbols under the covers.
 */
#define DARSHAN_WRAPPER_MAP(__func,__ret,__args,__fcall) \
	__ret __wrap_ ## __func __args { \
		__ret i; \
		i = __wrap_ ## __fcall; \
		return i; \
	}
74

75
#define MAP_OR_FAIL(__func)
76 77 78

#endif

79 80 81
/* default number of records to attempt to store for each module */
#define DARSHAN_DEF_MOD_REC_COUNT 1024

82 83 84 85 86 87 88 89 90
#ifdef HAVE_MPI
/*
 * module developers _can_ define a 'darshan_module_redux' function
 * to run collective MPI operations at shutdown time. Typically this
 * functionality has been used to reduce records shared globablly (given
 * in the 'shared_recs' array) into a single data record. Set to NULL
 * avoid any reduction steps.
 */
typedef void (*darshan_module_redux)(
91
    void *mod_buf, /* input parameter indicating module's buffer address */
92 93 94 95 96 97 98
    MPI_Comm mod_comm,  /* MPI communicator to run collectives with */
    darshan_record_id *shared_recs, /* list of shared data record ids */
    int shared_rec_count /* count of shared data records */
);
#endif
/*
 * module developers _must_ define a 'darshan_module_shutdown' function
99 100 101 102 103 104 105
 * for allowing darshan-core to call into a module and retrieve final
 * output data to be saved in the log.
 */
typedef void (*darshan_module_shutdown)(
    void **mod_buf, /* output parameter to save module buffer address */
    int *mod_buf_sz /* output parameter to save module buffer size */
);
106 107 108 109 110 111 112
typedef struct darshan_module_funcs
{
#ifdef HAVE_MPI
    darshan_module_redux mod_redux_func;
#endif
    darshan_module_shutdown mod_shutdown_func;
} darshan_module_funcs;
113

114 115 116 117 118
/* stores FS info from statfs calls for a given mount point */
struct darshan_fs_info
{
    int fs_type;
    int block_size;
119 120
    int ost_count;
    int mdt_count;
121 122
};

123 124 125 126 127 128 129 130 131 132 133 134 135 136
/* darshan_instrument_fs_data()
 *
 * Allow file system-specific modules to instrument data for the file
 * stored at 'path'. 'fs_type' is checked to determine the underlying
 * filesystem and calls into the corresponding file system instrumentation
 * module, if defined -- currently we only have a Lustre module. 'fd' is
 * the file descriptor corresponding to the file, which may be needed by
 * the file system to retrieve specific parameters.
 */
void darshan_instrument_fs_data(
    int fs_type,
    const char *path,
    int fd);

137 138 139
/*****************************************************
* darshan-core functions exported to darshan modules *
*****************************************************/
140

141 142 143 144
/* darshan_core_register_module()
 *
 * Register module identifier 'mod_id' with the darshan-core runtime
 * environment, allowing the module to store I/O characterization data.
145 146 147 148
 * 'mod_funcs' is a set of function pointers that implement module-specific
 * shutdown functionality (including a possible data reduction step when
 * using MPI). 'inout_mod_buf_size' is an input/output argument, with it
 * being set to the requested amount of module memory on input, and set to
149 150 151 152
 * the amount allocated by darshan-core on output. If Darshan is built with
 * MPI support, 'rank' is a pointer to an integer which will contain the
 * calling process's MPI rank on return. If given, 'sys_mem_alignment' is a
 * pointer to an integer which will contain the memory alignment value Darshan
153
 * was configured with on return.
154
 */
155
void darshan_core_register_module(
156
    darshan_module_id mod_id,
157
    darshan_module_funcs mod_funcs,
158
    int *inout_mod_buf_size,
159
    int *rank,
160
    int *sys_mem_alignment);
161

162 163 164 165 166
/* darshan_core_unregister_module()
 * 
 * Unregisters module identifier 'mod_id' with the darshan-core runtime,
 * removing the given module from the resulting I/O characterization log.
 */
167 168 169
void darshan_core_unregister_module(
    darshan_module_id mod_id);

170
/* darshan_core_gen_record_id()
171
 *
172
 * Returns the Darshan record ID correpsonding to input string 'name'.
173
 */
174
darshan_record_id darshan_core_gen_record_id(
175
    const char *name);
176

177 178
/* darshan_core_register_record()
 *
179 180
 * Register a record with the darshan-core runtime, allowing it to be
 * properly tracked and (potentially) correlated with records from other
181 182
 * modules. 'rec_id' is the Darshan record id as given by the
 * `darshan_core_gen_record_id` function. 'name' is the the name of the
183 184
 * Darshan record (e.g., the full file path), which is ignored if NULL is
 * passed. 'mod_id' is the identifier of the calling module. 'rec_len'
185
 * is the size of the record being registered with Darshan. If given,
Shane Snyder's avatar
Shane Snyder committed
186 187 188 189 190
 * 'fs_info' is a pointer to a structure containing information on
 * the underlying FS this record is associated with (determined by
 * matching the file name prefix with Darshan's list of tracked mount
 * points). Returns a pointer to the address the record should be
 * written to on success, NULL on failure.
191
 */
192
void *darshan_core_register_record(
193
    darshan_record_id rec_id,
194
    const char *name,
195
    darshan_module_id mod_id,
196
    int rec_len,
197
    struct darshan_fs_info *fs_info);
198

199 200 201 202 203 204 205 206

/* darshan_core_lookup_record_name()
 *
 * Looks up the name associated with a given Darshan record ID.
 */
char *darshan_core_lookup_record_name(
    darshan_record_id rec_id);

207 208 209 210 211
/* darshan_core_wtime()
 *
 * Returns the elapsed time relative to (roughly) the start of
 * the application.
 */
212
double darshan_core_wtime(void);
213

214 215 216 217 218 219 220 221 222
/* darshan_core_fprintf()
 *
 * Prints internal Darshan output on a given stream.
 */
void darshan_core_fprintf(
    FILE *stream,
    const char *format,
    ...);

223 224
/* darshan_core_excluded_path()
 *
225 226
 * Returns true (1) if the given file path 'path' is in Darshan's
 * list of excluded file paths, false (0) otherwise.
227 228 229 230
 */
int darshan_core_excluded_path(
    const char * path);

231 232 233 234 235 236 237 238 239
/* darshan_core_disabled_instrumentation
 *
 * Returns true (1) if Darshan has currently disabled instrumentation,
 * false (0) otherwise. If instrumentation is disabled, modules should
 * no longer update any file records as part of the intercepted function
 * wrappers.
 */
int darshan_core_disabled_instrumentation(void);

240
#endif /* __DARSHAN_H */