Commit 3a01d053 authored by Shane Snyder's avatar Shane Snyder

Some dev-modular docs edits

parent 6ef99ac9
...@@ -8,6 +8,8 @@ ...@@ -8,6 +8,8 @@
#include "darshan-log-format.h" #include "darshan-log-format.h"
/* TODO: X macro this stuff so counter indices and string names don't diverge */
/* integer statistics for POSIX file records */ /* integer statistics for POSIX file records */
enum darshan_posix_indices enum darshan_posix_indices
{ {
......
...@@ -140,7 +140,17 @@ struct darshan_module_funcs ...@@ -140,7 +140,17 @@ struct darshan_module_funcs
{ {
/* perform any necessary pre-shutdown steps */ /* perform any necessary pre-shutdown steps */
void (*begin_shutdown)(void); void (*begin_shutdown)(void);
/* perform any necessary steps prior to reducing */ /* retrieve module data to write to log file */
void (*get_output_data)(
void** buf, /* output parameter to save module buffer address */
int* size /* output parameter to save module buffer size */
);
/* shutdown module data structures */
void (*shutdown)(void);
/* (OPTIONAL) perform any necessary steps prior to performing a reduction
* of shared Darshan I/O records. To bypass shared file reduction mechanism,
* set this pointer to NULL.
*/
void (*setup_reduction)( void (*setup_reduction)(
darshan_record_id *shared_recs, /* input list of shared records */ darshan_record_id *shared_recs, /* input list of shared records */
int *shared_rec_count, /* in/out shared record count */ int *shared_rec_count, /* in/out shared record count */
...@@ -148,20 +158,18 @@ struct darshan_module_funcs ...@@ -148,20 +158,18 @@ struct darshan_module_funcs
void **recv_buf, /* recv buffer for shared file reduction (root only) */ void **recv_buf, /* recv buffer for shared file reduction (root only) */
int *rec_size /* size of records being stored for this module */ int *rec_size /* size of records being stored for this module */
); );
/* reduce records which are shared globally across this module */ /* (OPTIONAL) perform the actual shared file reduction operation. This
* operation follows the prototype of MPI_Op_create, which allows the
* specification of user-defined combination functions which may be used
* directly by MPI. To bypass shared file reduction mechanism, set this
* pointer to NULL.
*/
void (*record_reduction_op)( void (*record_reduction_op)(
void* infile_v, void* infile_v,
void* inoutfile_v, void* inoutfile_v,
int *len, int *len,
MPI_Datatype *datatype MPI_Datatype *datatype
); );
/* retrieve module data to write to log file */
void (*get_output_data)(
void** buf, /* output parameter to save module buffer address */
int* size /* output parameter to save module buffer size */
);
/* shutdown module data structures */
void (*shutdown)(void);
}; };
/* paths that darshan will not trace */ /* paths that darshan will not trace */
......
doc/darshan-dev-modular-runtime.png

30.2 KB | W: | H:

doc/darshan-dev-modular-runtime.png

34.3 KB | W: | H:

doc/darshan-dev-modular-runtime.png
doc/darshan-dev-modular-runtime.png
doc/darshan-dev-modular-runtime.png
doc/darshan-dev-modular-runtime.png
  • 2-up
  • Swipe
  • Onion skin
...@@ -74,8 +74,7 @@ In general, instrumentation modules are composed of: ...@@ -74,8 +74,7 @@ In general, instrumentation modules are composed of:
* internal functions for initializing and maintaining internal data structures and module-specific * internal functions for initializing and maintaining internal data structures and module-specific
I/O characterization data; I/O characterization data;
* a set of functions for interfacing with the Darshan runtime environment, including an optional * a set of functions for interfacing with the Darshan runtime environment
reduction operation to condense I/O data shared on all processes into a single data record.
A block diagram illustrating the interaction of an example POSIX instrumentation module and the A block diagram illustrating the interaction of an example POSIX instrumentation module and the
Darshan runtime environment is given below in Figure 1. Darshan runtime environment is given below in Figure 1.
...@@ -83,6 +82,30 @@ Darshan runtime environment is given below in Figure 1. ...@@ -83,6 +82,30 @@ Darshan runtime environment is given below in Figure 1.
.Darshan runtime environment .Darshan runtime environment
image::darshan-dev-modular-runtime.png[align="center"] image::darshan-dev-modular-runtime.png[align="center"]
As shown in Figure 1, the Darshan runtime environment is just a library (libdarshan) which
intercepts and instruments functions of interest made by an application to existing system
libraries. Two primary components of this library are `darshan-core` and `darshan-common`.
`darshan-core` is the central component which manages the initialization/shutdown of Darshan,
coordinates with active instrumentation modules, and writes I/O characterization logs to disk,
among other things. `darshan-core` intercepts `MPI_Init()` to initialize key internal data
stuctures and intercepts `MPI_Finalize()` to initiate Darshan's shutdown process. `darshan-common`
simply provides module developers with functionality that is likely to be reused across modules
to minimize development and maintenance costs. Instrumentation modules must utilize `darshan-core`
to register themselves and corresponding I/O records with Darshan so they can be added to the
output I/O characterization. While not shown in Figure 1, numerous modules can be registered
with Darshan at any given time and Darshan is capable of correlating records between these
modules.
In the next three subsections, we describe instrumentation modules, the `darshan-core` component,
and the `darshan-common` component in more detail. In
link:darshan-modularization.html#_adding_new_instrumentation_modules[Section 4], we provide the
required steps for integrating new instrumentation modules into Darshan. This section also includes
details on an example module that can serve as a minimal starting point for new module implementations.
In link:darshan-modularization.html#_shared_record_reductions[Section 5], we provide details on
implementing a shared record reduction operation within an instrumentation module. This optional
mechanism allows modules to compress records which are shared across all processes of an application,
minimizing the size of the resulting I/O characterization log.
==== Instrumentation modules ==== Instrumentation modules
The wrapper functions used to intercept I/O function calls of interest are central to the design of The wrapper functions used to intercept I/O function calls of interest are central to the design of
...@@ -106,6 +129,12 @@ environment to coordinate with modules while shutting down: ...@@ -106,6 +129,12 @@ environment to coordinate with modules while shutting down:
struct darshan_module_funcs struct darshan_module_funcs
{ {
void (*begin_shutdown)(void); void (*begin_shutdown)(void);
void (*get_output_data)(
void** buf,
int* size
);
void (*shutdown)(void);
/* OPTIONAL: shared record reductions ignored by setting setup_reduction to NULL */
void (*setup_reduction)( void (*setup_reduction)(
darshan_record_id *shared_recs, darshan_record_id *shared_recs,
int *shared_rec_count, int *shared_rec_count,
...@@ -113,17 +142,13 @@ struct darshan_module_funcs ...@@ -113,17 +142,13 @@ struct darshan_module_funcs
void **recv_buf, void **recv_buf,
int *rec_size int *rec_size
); );
/* OPTIONAL: shared record reductions ignored by setting record_reduction_op to NULL */
void (*record_reduction_op)( void (*record_reduction_op)(
void* a, void* a,
void* b, void* b,
int *len, int *len,
MPI_Datatype *datatype MPI_Datatype *datatype
); );
void (*get_output_data)(
void** buf,
int* size
);
void (*shutdown)(void);
}; };
`begin_shutdown()` `begin_shutdown()`
...@@ -147,17 +172,6 @@ the shared record reduction mechanism by setting the `setup_reduction` function ...@@ -147,17 +172,6 @@ the shared record reduction mechanism by setting the `setup_reduction` function
This is helpful in initial prototyping of a module, or in the case where a module would not maintain This is helpful in initial prototyping of a module, or in the case where a module would not maintain
I/O data which is shared across all processes. I/O data which is shared across all processes.
The shared record reduction mechanism is described in detail
link:darshan-modularization.html#_shared_record_reductions[here].
`record_reduction_op()`
This function implements the actual shared record reduction operation. Module developers can bypass
the shared record reduction mechanism by setting the `record_reduction_op` pointer equal to `NULL`.
The shared record reduction mechanism is described in detail
link:darshan-modularization.html#_shared_record_reductions[here].
`get_output_data()` `get_output_data()`
This function is responsible for passing back a single buffer storing all data this module is This function is responsible for passing back a single buffer storing all data this module is
...@@ -173,6 +187,11 @@ characterization. ...@@ -173,6 +187,11 @@ characterization.
This function is a signal from Darshan that it is safe to shutdown. It should clean up and free This function is a signal from Darshan that it is safe to shutdown. It should clean up and free
all internal data structures. all internal data structures.
`setup_reduction()` and `record_reduction_op()` are optional function pointers which can be
implemented to utilize Darshan's shared I/O record reduction mechanism, described in detail in
link:darshan-modularization.html#_shared_record_reductions[Section 5]. Module developers can
bypass this mechanism by setting these function pointers to NULL.
==== darshan-core ==== darshan-core
Within darshan-runtime, the darshan-core component manages the initialization and shutdown of the Within darshan-runtime, the darshan-core component manages the initialization and shutdown of the
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment