darshan.h 5.18 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
Shane Snyder's avatar
Shane Snyder committed
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

Shane Snyder's avatar
Shane Snyder committed
56
/* module developers provide the following functions to darshan-core */
57
struct darshan_module_funcs
58
{
59
60
61
62
63
    /* perform any necessary pre-shutdown steps
     *
     * NOTE: this typically includes disabling wrapper functions so
     * darshan-core can shutdown in a consistent state.
     */
64
    void (*begin_shutdown)(void);
65
66
67
68
69
70
71
    /* retrieve module data to write to log file
     *
     * 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.
     */
Shane Snyder's avatar
Shane Snyder committed
72
    void (*get_output_data)(
73
74
75
76
77
        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 */
Shane Snyder's avatar
Shane Snyder committed
78
79
80
    );
    /* shutdown module data structures */
    void (*shutdown)(void);
81
82
};

83
84
85
/*****************************************************
* darshan-core functions exported to darshan modules *
*****************************************************/
86

87
88
89
90
91
92
93
94
95
96
97
/* darshan_core_register_module()
 *
 * Register module identifier 'mod_id' with the darshan-core runtime
 * environment, allowing the module to store I/O characterization data.
 * 'funcs' is a pointer to a structure containing each of the function
 * pointers required by darshan-core to shut down the module. The function
 * returns the following integers passed in as pointers: 'my_rank' is the
 * MPI rank of the calling process, 'mod_mem_limit' is the maximum amount
 * of memory the module may use, and 'sys_mem_alignment' is the configured
 * memory alignment value Darshan was configured with.
 */
98
void darshan_core_register_module(
99
    darshan_module_id mod_id,
100
    struct darshan_module_funcs *funcs,
101
102
    void **mod_buf,
    int *mod_buf_size,
103
    int *my_rank,
104
    int *sys_mem_alignment);
105

106
107
108
109
110
/* 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.
 */
111
112
113
void darshan_core_unregister_module(
    darshan_module_id mod_id);

114
115
116
117
118
/* darshan_core_register_record()
 *
 * Register the Darshan record given by 'name' with the darshan-core
 * runtime, allowing it to be properly tracked and (potentially)
 * correlated with records from other modules. 'len' is the size of
119
120
121
122
123
124
125
126
 * the name pointer (string length for string names), and 'printable_flag'
 * indicates whether the name is a string. 'mod_limit_flag' is set if
 * the calling module is out of memory (to prevent darshan-core from
 * creating new records and to just search existing records)  and 'mod_id'
 * is the identifier of the calling module. 'rec_id' is an output pointer
 * storing the correspoing Darshan record identifier and 'file_alignment'
 * is an output pointer storing the file system alignment value for the
 * given record.
127
 */
Shane Snyder's avatar
Shane Snyder committed
128
void darshan_core_register_record(
129
130
    void *name,
    int len,
131
    darshan_module_id mod_id,
132
133
    int printable_flag,
    int mod_limit_flag,
134
135
    darshan_record_id *rec_id,
    int *file_alignment);
136

137
138
139
140
141
142
143
/* darshan_core_unregister_record()
 *
 * Unregister record identifier 'rec_id' in the darshan-core runtime.
 * This unregister is only in the context of module identifier 'mod_id',
 * meaning that if the file record has other module's associated with
 * it, then the record won't be completely removed.
 */
Shane Snyder's avatar
Shane Snyder committed
144
145
146
147
void darshan_core_unregister_record(
    darshan_record_id rec_id,
    darshan_module_id mod_id);

148
149
150
151
152
/* darshan_core_wtime()
 *
 * Returns the elapsed time relative to (roughly) the start of
 * the application.
 */
153
double darshan_core_wtime(void);
154

155
156
157
158
159
160
161
162
/* darshan_core_excluded_path()
 *
 * Returns true (1) if the given file path is in Darshan's list of
 * excluded file paths, false (0) otherwise.
 */
int darshan_core_excluded_path(
    const char * path);

163
#endif /* __DARSHAN_H */