darshan.h 4.91 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 13
#ifndef __DARSHAN_H
#define __DARSHAN_H

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

15
#include "darshan-log-format.h"
16
#include "darshan-common.h"
17

18 19 20 21
/* macros for declaring wrapper functions and calling MPI routines
 * consistently regardless of whether static or dynamic linking is used
 */
#ifdef DARSHAN_PRELOAD
22

23 24 25
#include <dlfcn.h>
#include <stdlib.h>

26 27
#define DARSHAN_FORWARD_DECL(__func,__ret,__args) \
  __ret (*__real_ ## __func)__args = NULL
28

29
#define DARSHAN_DECL(__func) __func
30

31
#define DARSHAN_MPI_CALL(__func) __real_ ## __func
32

33 34
#define MAP_OR_FAIL(__func) \
    if (!(__real_ ## __func)) \
35
    { \
36 37 38
        __real_ ## __func = dlsym(RTLD_NEXT, #__func); \
        if(!(__real_ ## __func)) { \
           fprintf(stderr, "Darshan failed to map symbol: %s\n", #__func); \
39 40 41 42 43 44
           exit(1); \
       } \
    }

#else

45 46
#define DARSHAN_FORWARD_DECL(__name,__ret,__args) \
  extern __ret __real_ ## __name __args;
47 48 49

#define DARSHAN_DECL(__name) __wrap_ ## __name

50
#define DARSHAN_MPI_CALL(__func) __func
51

52
#define MAP_OR_FAIL(__func)
53 54 55

#endif

56 57 58
/* default number of records to attempt to store for each module */
#define DARSHAN_DEF_MOD_REC_COUNT 1024

59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74
/* module developers must define a 'darshan_module_shutdown' function
 * for allowing darshan-core to call into a module and retrieve final
 * output data to be saved in the log.
 *
 * NOTE: module developers can use this 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.
 */
typedef void (*darshan_module_shutdown)(
    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 */
    void **mod_buf, /* output parameter to save module buffer address */
    int *mod_buf_sz /* output parameter to save module buffer size */
);
75

76 77 78
/*****************************************************
* darshan-core functions exported to darshan modules *
*****************************************************/
79

80 81 82 83
/* darshan_core_register_module()
 *
 * Register module identifier 'mod_id' with the darshan-core runtime
 * environment, allowing the module to store I/O characterization data.
84 85
 * 'mod_shutdown_func is a pointer to a function responsible for
 * shutting down the module and returning final output data to darshan-core.
86 87 88 89 90 91 92
 * '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
 * the amount allocated by darshan-core on output. If given, '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
 * was configured with on return.
93
 */
94
void darshan_core_register_module(
95
    darshan_module_id mod_id,
96
    darshan_module_shutdown mod_shutdown_func,
97
    int *inout_mod_buf_size,
98
    int *rank,
99
    int *sys_mem_alignment);
100

101 102 103 104 105
/* 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.
 */
106 107 108
void darshan_core_unregister_module(
    darshan_module_id mod_id);

109
/* darshan_core_gen_record_id()
110
 *
111
 * Returns the Darshan record ID correpsonding to input string 'name'.
112
 */
113
darshan_record_id darshan_core_gen_record_id(
114
    const char *name);
115

116 117
/* darshan_core_register_record()
 *
118 119
 * Register a record with the darshan-core runtime, allowing it to be
 * properly tracked and (potentially) correlated with records from other
120 121 122 123 124 125 126
 * 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
 * Darshan record (e.g., the full file path), which for now is just a
 * string. 'mod_id' is the identifier of the calling module. 'rec_len'
 * is the size of the record being registered with Darshan. If given,
 * 'file_alignment' is a pointer to an integer which on return will
 * contain the corresponding file system alignment of the file system
127 128
 * path 'name' resides on. Returns a pointer to the address the record
 * should be written to on success, NULL on failure.
129
 */
130
void *darshan_core_register_record(
131
    darshan_record_id rec_id,
132
    const char *name,
133
    darshan_module_id mod_id,
134
    int rec_len,
135
    int *file_alignment);
136

137 138 139 140 141
/* darshan_core_wtime()
 *
 * Returns the elapsed time relative to (roughly) the start of
 * the application.
 */
142
double darshan_core_wtime(void);
143

144 145
/* darshan_core_excluded_path()
 *
146 147
 * Returns true (1) if the given file path 'path' is in Darshan's
 * list of excluded file paths, false (0) otherwise.
148 149 150 151
 */
int darshan_core_excluded_path(
    const char * path);

152
#endif /* __DARSHAN_H */