883 строки
34 KiB
C
883 строки
34 KiB
C
/*
|
|
* Copyright (c) 2007 High Performance Computing Center Stuttgart,
|
|
* University of Stuttgart. All rights reserved.
|
|
* Copyright (c) 2007-2008 Cisco Systems, Inc. All rights reserved.
|
|
* Copyright (c) 2007-2013 The University of Tennessee and The University of
|
|
* Tennessee Research Foundation. All rights reserved.
|
|
* Copyright (c) 2012-2013 Inria. All rights reserved.
|
|
* $COPYRIGHT$
|
|
*
|
|
* Additional copyrights may follow
|
|
*
|
|
* Some text copied from and references made to mpi_interface.h.
|
|
*
|
|
* Copyright (C) 2000-2004 by Etnus, LLC
|
|
* Copyright (C) 1999 by Etnus, Inc.
|
|
* Copyright (C) 1997-1998 Dolphin Interconnect Solutions Inc.
|
|
*
|
|
* $HEADER$
|
|
*/
|
|
|
|
#ifndef __MPIDBG_INTERFACE_H__
|
|
#define __MPIDBG_INTERFACE_H__ 1
|
|
|
|
#include "ompi_config.h"
|
|
|
|
/*
|
|
* This file provides interface functions for a debugger to gather
|
|
* additional information about MPI handles.
|
|
*/
|
|
#include <sys/types.h>
|
|
|
|
/* Include the Etnus debugger message queue interface so that we can
|
|
use much of its infrastructure (e.g., the mqs_basic_callbacks,
|
|
mqs_image_callbacks, and mqs_process_callbacks). */
|
|
#define FOR_MPI2 0
|
|
#include "msgq_interface.h"
|
|
|
|
/**************************************************************************
|
|
* Types and macros
|
|
**************************************************************************/
|
|
|
|
enum {
|
|
MPIDBG_MAX_OBJECT_NAME = MPI_MAX_OBJECT_NAME
|
|
};
|
|
enum {
|
|
MPIDBG_MAX_FILENAME = 1024
|
|
};
|
|
enum {
|
|
MPIDBG_INTERFACE_VERSION = 1
|
|
};
|
|
|
|
|
|
/*-----------------------------------------------------------------------
|
|
* Global initialization information for the DLL
|
|
*-----------------------------------------------------------------------*/
|
|
|
|
/* Structure containing types for C and C++ MPI handles */
|
|
struct mpidbg_handle_info_t {
|
|
/* C handle types. They are typically pointers to something or
|
|
integers. */
|
|
/* Back-end type for MPI_Aint */
|
|
mqs_type *hi_c_aint;
|
|
/* Back-end type for MPI_Comm */
|
|
mqs_type *hi_c_comm;
|
|
/* Back-end type for MPI_Datatype */
|
|
mqs_type *hi_c_datatype;
|
|
/* Back-end type for MPI_Errhandler */
|
|
mqs_type *hi_c_errhandler;
|
|
/* Back-end type for MPI_File */
|
|
mqs_type *hi_c_file;
|
|
/* Back-end type for MPI_Group */
|
|
mqs_type *hi_c_group;
|
|
/* Back-end type for MPI_Info */
|
|
mqs_type *hi_c_info;
|
|
/* Back-end type for MPI_Offset */
|
|
mqs_type *hi_c_offset;
|
|
/* Back-end type for MPI_Op */
|
|
mqs_type *hi_c_op;
|
|
/* Back-end type for MPI_Request */
|
|
mqs_type *hi_c_request;
|
|
/* Back-end type for MPI_Status */
|
|
mqs_type *hi_c_status;
|
|
/* Back-end type for MPI_Win */
|
|
mqs_type *hi_c_win;
|
|
|
|
/* C++ handle types. Note that these will always be *objects*,
|
|
never pointers. */
|
|
/* Back-end type for MPI::Aint */
|
|
mqs_type *hi_cxx_aint;
|
|
/* Back-end type for MPI::Comm */
|
|
mqs_type *hi_cxx_comm;
|
|
/* Back-end type for MPI::Intracomm */
|
|
mqs_type *hi_cxx_intracomm;
|
|
/* Back-end type for MPI::Intercomm */
|
|
mqs_type *hi_cxx_intercomm;
|
|
/* Back-end type for MPI::Graphcomm */
|
|
mqs_type *hi_cxx_graphcomm;
|
|
/* Back-end type for MPI::Cartcomm */
|
|
mqs_type *hi_cxx_cartcomm;
|
|
/* Back-end type for MPI::Datatype */
|
|
mqs_type *hi_cxx_datatype;
|
|
/* Back-end type for MPI::Errhandler */
|
|
mqs_type *hi_cxx_errhandler;
|
|
/* Back-end type for MPI::File */
|
|
mqs_type *hi_cxx_file;
|
|
/* Back-end type for MPI::Group */
|
|
mqs_type *hi_cxx_group;
|
|
/* Back-end type for MPI::Info */
|
|
mqs_type *hi_cxx_info;
|
|
/* Back-end type for MPI::Offset */
|
|
mqs_type *hi_cxx_offset;
|
|
/* Back-end type for MPI::Op */
|
|
mqs_type *hi_cxx_op;
|
|
/* Back-end type for MPI::Request */
|
|
mqs_type *hi_cxx_request;
|
|
/* Back-end type for MPI::Prequest */
|
|
mqs_type *hi_cxx_prequest;
|
|
/* Back-end type for MPI::Grequest */
|
|
mqs_type *hi_cxx_grequest;
|
|
/* Back-end type for MPI::Status */
|
|
mqs_type *hi_cxx_status;
|
|
/* Back-end type for MPI::Win */
|
|
mqs_type *hi_cxx_win;
|
|
};
|
|
|
|
enum mpidbg_return_codes_t {
|
|
/* Success */
|
|
MPIDBG_SUCCESS,
|
|
/* Something was not found */
|
|
MPIDBG_ERR_NOT_FOUND,
|
|
/* Something is not supported */
|
|
MPIDBG_ERR_NOT_SUPPORTED,
|
|
/* Something is out of range */
|
|
MPIDBG_ERR_OUT_OF_RANGE,
|
|
/* Something is not available */
|
|
MPIDBG_ERR_UNAVAILABLE,
|
|
/* Ran out of memory */
|
|
MPIDBG_ERR_NO_MEM,
|
|
/* Sentinel max value */
|
|
MPIDBG_MAX_RETURN_CODE
|
|
};
|
|
|
|
/*-----------------------------------------------------------------------
|
|
* General data structures
|
|
*-----------------------------------------------------------------------*/
|
|
|
|
/* Information about MPI processes */
|
|
struct mpidbg_process_t {
|
|
/* JMS: need something to uniquely ID MPI processes in the
|
|
presence of MPI_COMM_SPAWN */
|
|
|
|
/* Global rank in MPI_COMM_WORLD */
|
|
int mpi_comm_world_rank;
|
|
};
|
|
/* ==> JMS Should we just use mqs_process_location instead? George
|
|
thinks that this is unncessary -- perhaps due to the fact that we
|
|
could use mqs_process_location...? Need to get some feedback from
|
|
others on this one. Need to check Euro PVM/MPI '06 paper... */
|
|
|
|
/* General name -> handle address mappings. This is an optional type
|
|
that is used to describe MPI's predefined handles if the
|
|
pre-defined names do not appear as symbols in the MPI process.
|
|
E.g., if MPI_COMM_WORLD is a #define that maps to some other value,
|
|
this data structure can be used to map the string "MPI_COMM_WORLD"
|
|
to the actual value of the handle that it corresponds to (e.g., 0
|
|
or a pointer value). */
|
|
struct mpidbg_name_map_t {
|
|
/* Name of the handle */
|
|
char *map_name;
|
|
|
|
/* Handle that the name corresponds to. Will be 0/NULL if there
|
|
is no corresponding back-end object. */
|
|
mqs_taddr_t map_handle;
|
|
};
|
|
|
|
/* MPI attribute / value pairs. Include both a numeric and string
|
|
key; pre-defined MPI keyvals (e.g., MPI_TAG_MAX) have a
|
|
human-readable string name. The string will be NULL for
|
|
non-predefined keyvals. */
|
|
struct mpidbg_attribute_pair_t {
|
|
/* Keyval */
|
|
int keyval;
|
|
/* Keyval name; will be non-NULL for attributes that have a
|
|
human-readable name (e.g., MPI predefined keyvals) */
|
|
char *keyval_name;
|
|
/* Value */
|
|
char *value;
|
|
};
|
|
|
|
/*-----------------------------------------------------------------------
|
|
* Communicators
|
|
*-----------------------------------------------------------------------*/
|
|
|
|
/* Using an enum instead of #define because debuggers can show the
|
|
*names* of enum values, not just the values. */
|
|
enum mpidbg_comm_capabilities_t {
|
|
/* Whether this MPI DLL supports returning basic information about
|
|
communicators */
|
|
MPIDBG_COMM_CAP_BASIC = 0x01,
|
|
/* Whether this MPI DLL supports returning names of
|
|
communicators */
|
|
MPIDBG_COMM_CAP_STRING_NAMES = 0x02,
|
|
/* Whether this MPI DLL supports indicating whether a communicator
|
|
has been freed by the user application */
|
|
MPIDBG_COMM_CAP_FREED_HANDLE = 0x04,
|
|
/* Whether this MPI DLL supports indicating whether a communicator
|
|
object has been freed by the MPI implementation or not */
|
|
MPIDBG_COMM_CAP_FREED_OBJECT = 0x08,
|
|
/* Whether this MPI DLL supports returning the list of MPI request
|
|
handles that are pending on a communicator */
|
|
MPIDBG_COMM_CAP_REQUEST_LIST = 0x10,
|
|
/* Whether this MPI DLL supports returning the list of MPI window
|
|
handles that were derived from a given communicator */
|
|
MPIDBG_COMM_CAP_WINDOW_LIST = 0x20,
|
|
/* Whether this MPI DLL supports returning the list of MPI file
|
|
handles that were derived from a given communicator */
|
|
MPIDBG_COMM_CAP_FILE_LIST = 0x40,
|
|
/* Sentinel max value */
|
|
MPIDBG_COMM_CAP_MAX
|
|
};
|
|
|
|
enum mpidbg_comm_info_bitmap_t {
|
|
/* Predefined communicator if set (user-defined if not set) */
|
|
MPIDBG_COMM_INFO_PREDEFINED = 0x01,
|
|
/* Whether this communicator is a cartesian communicator or not
|
|
(mutually exclusive with _GRAPH and _INTERCOMM) */
|
|
MPIDBG_COMM_INFO_CARTESIAN = 0x02,
|
|
/* Whether this communicator is a graph communicator or not
|
|
(mutually exclusive with _CARTESIAN and _INTERCOMM) */
|
|
MPIDBG_COMM_INFO_GRAPH = 0x04,
|
|
/* If a cartesian or graph communicator, whether the processes in
|
|
this communicator were re-ordered when the topology was
|
|
assigned. */
|
|
MPIDBG_COMM_INFO_TOPO_REORDERED = 0x08,
|
|
/* Whether this is an intercommunicator or not (this communicator
|
|
is an intracommunicator if this flag is not yet). */
|
|
MPIDBG_COMM_INFO_INTERCOMM = 0x10,
|
|
/* This communicator has been marked for freeing by the user
|
|
application if set */
|
|
MPIDBG_COMM_INFO_FREED_HANDLE = 0x20,
|
|
/* This communicator has actually been freed by the MPI
|
|
implementation if set */
|
|
MPIDBG_COMM_INFO_FREED_OBJECT = 0x40,
|
|
/* The queried communicator is MPI_COMM_NULL */
|
|
MPIDBG_COMM_INFO_COMM_NULL = 0x80,
|
|
/* The queried communicator has a distributed graph topology attached to it */
|
|
MPIDBG_COMM_INFO_DIST_GRAPH = 0x00000400,
|
|
/* Sentinel max value */
|
|
MPIDBG_COMM_INFO_MAX
|
|
};
|
|
|
|
struct mpidbg_comm_info_t {
|
|
/* Name of the MPI_COMM */
|
|
char comm_name[MPIDBG_MAX_OBJECT_NAME];
|
|
|
|
/* Bit flags describing the communicator */
|
|
enum mpidbg_comm_info_bitmap_t comm_bitflags;
|
|
|
|
/* This process' rank within this communicator */
|
|
int comm_rank;
|
|
/* The communicator's size */
|
|
int comm_size;
|
|
|
|
/* Number of processes in the local group */
|
|
int comm_num_local_procs;
|
|
/* Information about each process in the local group (in
|
|
communicator rank order, length: comm_num_local_procs) */
|
|
struct mpidbg_process_t *comm_local_procs;
|
|
|
|
/* For intercommunicators, the number of processes in the remote
|
|
group */
|
|
int comm_num_remote_procs;
|
|
/* For intercommunicators, information about each process in the
|
|
remote group (in communicator rank order, length:
|
|
comm_num_remote_procs) */
|
|
struct mpidbg_process_t *comm_remote_procs;
|
|
|
|
/* For cartesian communicators, the number of dimensions */
|
|
int comm_cart_num_dims;
|
|
/* For cartesian communicators, an array of dimension lengths
|
|
(length: cart_comm_num_dims) */
|
|
int *comm_cart_dims;
|
|
/* For cartesian communicators, an array of boolean values
|
|
indicating whether each dimension is periodic or not (length:
|
|
cart_comm_num_dims) */
|
|
int8_t *comm_cart_periods;
|
|
|
|
/* For graph communicators, the number of nodes */
|
|
int comm_graph_num_nodes;
|
|
/* For graph communicators, an array of the node degrees (length:
|
|
comm_graph_num_nodes) */
|
|
int *comm_graph_index;
|
|
/* For graph communicators, an array of the edges (length:
|
|
comm_graph_num_nodes) */
|
|
int *comm_graph_edges;
|
|
|
|
/* C handle */
|
|
mqs_taddr_t comm_c_handle;
|
|
/* Fortran handle; will be MPIDBG_ERR_UNAVAILABLE if currently
|
|
unavailable or MPIDBG_ERR_NOT_SUPPORTED if not supported */
|
|
int comm_fortran_handle;
|
|
|
|
/* Number of attributes defined on this communicator */
|
|
int comm_num_attrs;
|
|
/* Array of attribute keyval/value pairs defined on this
|
|
communicator (length: comm_num_attrs) */
|
|
struct mpidbg_attribute_pair_t *comm_attrs;
|
|
|
|
/* Number of ongoing requests within this communicator, or
|
|
MPIDBG_ERR_NOT_SUPPORTED */
|
|
int comm_num_pending_requests;
|
|
/* If comm_num_pending_requests != MPIDBG_ERR_NOT_SUPPORTED, an
|
|
array of ongoing request handles attached on this
|
|
communicator (length: comm_num_pending_requests) */
|
|
mqs_taddr_t *comm_pending_requests;
|
|
|
|
/* Number of MPI windows derived from this communicator, or
|
|
MPIDBG_ERR_NOT_SUPPORTED */
|
|
int comm_num_derived_windows;
|
|
/* If comm_num_derived_windows != MPIDBG_ERR_NOT_SUPPORTED, an
|
|
array of window handles derived from this communicator (length:
|
|
com_num_derived_windows) */
|
|
mqs_taddr_t *comm_derived_windows;
|
|
|
|
/* Number of MPI files derived from this communicator, or
|
|
MPIDBG_ERR_NOT_SUPPORTED */
|
|
int comm_num_derived_files;
|
|
/* If comm_num_derived_files != MPIDBG_ERR_NOT_SUPPORTED, an array
|
|
of file handles derived from this communicator (length:
|
|
comm_num_derived_files) */
|
|
mqs_taddr_t *comm_derived_files;
|
|
};
|
|
|
|
|
|
/*-----------------------------------------------------------------------
|
|
* Requests
|
|
*-----------------------------------------------------------------------*/
|
|
|
|
/* Using an enum instead of #define because debuggers can show the
|
|
*names* of enum values, not just the values. */
|
|
enum mpidbg_request_capabilities_t {
|
|
/* Whether this MPI DLL supports returning basic information about
|
|
requests */
|
|
MPIDBG_REQUEST_CAP_BASIC = 0x01,
|
|
/* Sentinel max value */
|
|
MPIDBG_REQUEST_CAP_MAX
|
|
};
|
|
|
|
enum mpidbg_request_info_bitmap_t {
|
|
/* Predefined request if set (user-defined if not set) */
|
|
MPIDBG_REQUEST_INFO_PREDEFINED = 0x01,
|
|
/* Sentinel max value */
|
|
MPIDBG_REQUEST_INFO_MAX
|
|
};
|
|
|
|
struct mpidbg_request_info_t {
|
|
/* Bit flags describing the error handler */
|
|
enum mpidbg_request_info_bitmap_t req_bitflags;
|
|
|
|
/* C handle */
|
|
mqs_taddr_t req_c_handle;
|
|
/* Fortran handle; will be MPIDBG_ERR_UNAVAILABLE if currently
|
|
unavailable or MPIDBG_ERR_NOT_SUPPORTED if not supported */
|
|
int req_fortran_handle;
|
|
};
|
|
|
|
/*-----------------------------------------------------------------------
|
|
* Statuses
|
|
*-----------------------------------------------------------------------*/
|
|
|
|
enum mpidbg_status_capabilities_t {
|
|
/* Whether this MPI DLL supports returning basic information about
|
|
statuses */
|
|
MPIDBG_STATUS_CAP_BASIC = 0x01,
|
|
/* Sentinel max value */
|
|
MPIDBG_STATUS_CAP_MAX
|
|
};
|
|
|
|
enum mpidbg_status_info_bitmap_t {
|
|
/* Predefined status if set (user-defined if not set) */
|
|
MPIDBG_STATUS_INFO_PREDEFINED = 0x01,
|
|
/* Sentinel max value */
|
|
MPIDBG_STATUS_INFO_MAX
|
|
};
|
|
|
|
struct mpidbg_status_info_t {
|
|
/* Bit flags describing the error handler */
|
|
enum mpidbg_status_info_bitmap_t status_bitflags;
|
|
};
|
|
|
|
/*-----------------------------------------------------------------------
|
|
* Error handlers
|
|
*-----------------------------------------------------------------------*/
|
|
|
|
/* Using an enum instead of #define because debuggers can show the
|
|
*names* of enum values, not just the values. */
|
|
enum mpidbg_errhandler_capabilities_t {
|
|
/* Whether this MPI DLL supports returning basic information about
|
|
error handlers */
|
|
MPIDBG_ERRH_CAP_BASIC = 0x01,
|
|
/* Whether this MPI DLL supports returning names of the predefined
|
|
error handlers */
|
|
MPIDBG_ERRH_CAP_STRING_NAMES = 0x02,
|
|
/* Whether this MPI DLL supports indicating whether an error
|
|
handler has been freed by the user application */
|
|
MPIDBG_ERRH_CAP_FREED_HANDLE = 0x04,
|
|
/* Whether this MPI DLL supports indicating whether an error
|
|
handler object has been freed by the MPI implementation or
|
|
not */
|
|
MPIDBG_ERRH_CAP_FREED_OBJECT = 0x08,
|
|
/* Whether this MPI DLL supports returning the list of MPI handles
|
|
that an MPI error handler is attached to */
|
|
MPIDBG_ERRH_CAP_HANDLE_LIST = 0x10,
|
|
/* Sentinel max value */
|
|
MPIDBG_ERRH_CAP_MAX
|
|
};
|
|
|
|
enum mpidbg_errhandler_info_bitmap_t {
|
|
/* Predefined error handler if set (user-defined if not set) */
|
|
MPIDBG_ERRH_INFO_PREDEFINED = 0x01,
|
|
/* Communicator error handler if set */
|
|
MPIDBG_ERRH_INFO_COMMUNICATOR = 0x02,
|
|
/* File error handler if set */
|
|
MPIDBG_ERRH_INFO_FILE = 0x04,
|
|
/* Window error handler if set */
|
|
MPIDBG_ERRH_INFO_WINDOW = 0x08,
|
|
/* Callback is in C if set (Fortran if not set) */
|
|
MPIDBG_ERRH_INFO_C_CALLBACK = 0x10,
|
|
/* This errorhandler has been marked for freeing by the user
|
|
application if set */
|
|
MPIDBG_ERRH_INFO_FREED_HANDLE = 0x20,
|
|
/* This errorhandler has actually been freed by the MPI
|
|
implementation if set */
|
|
MPIDBG_ERRH_INFO_FREED_OBJECT = 0x40,
|
|
/* Sentinel max value */
|
|
MPIDBG_ERRH_INFO_MAX
|
|
};
|
|
|
|
struct mpidbg_errhandler_info_t {
|
|
/* String name; only relevant for predefined errorhandlers. If
|
|
not a predefined errorhandler, eh_name[0] will be '\0'; */
|
|
char eh_name[MPIDBG_MAX_OBJECT_NAME];
|
|
|
|
/* Bit flags describing the error handler */
|
|
enum mpidbg_errhandler_info_bitmap_t eh_bitflags;
|
|
|
|
/* C handle */
|
|
mqs_taddr_t eh_c_handle;
|
|
/* Fortran handle; will be MPIDBG_ERR_UNAVAILABLE if currently
|
|
unavailable or MPIDBG_ERR_NOT_SUPPORTED if not supported */
|
|
int eh_fortran_handle;
|
|
|
|
/* Number of MPI handles that this error handler is attached to.
|
|
MPIDBG_ERR_NOT_SUPPORTED means that this information is not
|
|
supported by the DLL. */
|
|
int16_t eh_refcount;
|
|
/* If eh_refcount != MPIDBG_ERR_NOT_SUPPORTED, list of handles
|
|
that are using this error handler (length: eh_refcount). */
|
|
mqs_taddr_t *eh_handles;
|
|
|
|
/* Address of the user-defined error handler (will be 0 for
|
|
predefined error handlers). Note that each of the 3 C
|
|
callbacks contain an MPI handle; the debugger will need to
|
|
figure out the appropriate size for these types depending on
|
|
the platform and MPI implementation. This value will be NULL
|
|
if MPIDBG_ERRH_INFO_PREDEFINED is set on the flags. */
|
|
mqs_taddr_t eh_callback_func;
|
|
};
|
|
|
|
/**************************************************************************
|
|
* Global variables
|
|
*
|
|
* mpidbg_dll_locations is in the MPI application; all others are in
|
|
* the DLL.
|
|
**************************************************************************/
|
|
|
|
/* Array of filenames instantiated IN THE MPI APPLICATION (*NOT* in
|
|
the DLL) that provides an set of locations where DLLs may be found.
|
|
The last pointer in the array will be a NULL sentinel value. The
|
|
debugger can scan the entries in the array, find one that matches
|
|
the debugger (by examining a) whether the dlopen works or not, and
|
|
b) if the dlopen succeeds, examine mpidbg_dll_is_big_endian and
|
|
mpidbg_dll_bitness), and try to dynamically open the dl_filename.
|
|
Notes:
|
|
|
|
1. It is not an error if a dl_filename either does not exist or is
|
|
otherwise un-openable (the debugger can just try the next
|
|
match).
|
|
2. This array values are not valid until MPIR_Breakpoint.
|
|
3. If a filename is absolute, the debugger will attempt to load
|
|
exactly that. If the filename is relative, the debugger may try
|
|
a few prefix variations to find the DLL.
|
|
*/
|
|
extern char **mpidbg_dll_locations;
|
|
|
|
/* Global variable *in the DLL* describing whether this DLL is big or
|
|
little endian (1 = big endian, 0 = little endian). This value is
|
|
valid immediately upon opening of the DLL. */
|
|
extern char mpidbg_dll_is_big_endian;
|
|
|
|
/* Global variable *in the DLL* describing the bitness of the DLL (8,
|
|
16, 32, 64, ...). This value is valid immediately upon opening of
|
|
the DLL. */
|
|
extern char mpidbg_dll_bitness;
|
|
|
|
/* Global variable *in the DLL* describing the DLL's capabilties with
|
|
regards to communicators. This value is valid after a successfull
|
|
call to mpidbg_init_per_process(). */
|
|
extern enum mpidbg_comm_capabilities_t mpidbg_comm_capabilities;
|
|
|
|
/* Global variable *in the DLL* that is an array of MPI communicator
|
|
handle names -> handle mappings (the last entry in the array is
|
|
marked by a NULL string value). For example, MPI_COMM_WORLD may
|
|
not appear as a symbol in an MPI process, but the debugger needs to
|
|
be able to map this name to a valid handle. MPI implementations
|
|
not requiring this mapping can either have a NULL value for this
|
|
variable or have a single entry that has a NULL string value. This
|
|
variable is not valid until after a successfull call to
|
|
mpidbg_init_per_process(). */
|
|
extern struct mpidbg_name_map_t *mpidbg_comm_name_map;
|
|
|
|
/* Global variable *in the DLL* describing the DLL's capabilties with
|
|
regards to error handlers. This value is valid after a successfull
|
|
call to mpidbg_init_per_process(). */
|
|
extern enum mpidbg_errhandler_capabilities_t mpidbg_errhandler_capabilities;
|
|
|
|
/* Global variable *in the DLL* that is an array of MPI error handler
|
|
handle names -> handle mappings. It is analogous to
|
|
mpidbg_comm_name_map; see above for details. */
|
|
extern struct mpidbg_name_map_t *mpidbg_errhandler_name_map;
|
|
|
|
/**************************************************************************
|
|
* Functions
|
|
**************************************************************************/
|
|
|
|
/*-----------------------------------------------------------------------
|
|
* DLL infrastructure functions
|
|
*-----------------------------------------------------------------------*/
|
|
|
|
/* This function must be called once before any other mpidbg_*()
|
|
function is called, and before most other global mpidbg_* data is
|
|
read. It is only necessary to call this function once for a given
|
|
debugger instantiation. This function will initialize all mpidbg
|
|
global state, to include setting all relevant global capability
|
|
flags.
|
|
|
|
Parameters:
|
|
|
|
IN: callbacks: Table of pointers to the debugger functions. The DLL
|
|
need only save the pointer, the debugger promises to
|
|
maintain the table of functions valid for as long as
|
|
needed. The table remains the property of the
|
|
debugger, and should not be altered or deallocated
|
|
by the DLL. This applies to all of the callback
|
|
tables.
|
|
|
|
This function will return:
|
|
|
|
MPIDBG_SUCCESS: if all initialization went well
|
|
MPIDBG_ERR_*: if something went wrong.
|
|
*/
|
|
int mpidbg_init_once(const mqs_basic_callbacks *callbacks);
|
|
|
|
/*-----------------------------------------------------------------------*/
|
|
|
|
/* Query the DLL to find out what version of the interface it
|
|
supports.
|
|
|
|
Parameters:
|
|
|
|
None.
|
|
|
|
This function will return:
|
|
|
|
MPIDBG_INTERFACE_VERSION
|
|
*/
|
|
|
|
int mpidbg_interface_version_compatibility(void);
|
|
|
|
/*-----------------------------------------------------------------------*/
|
|
|
|
/* Returns a string describing this DLL.
|
|
|
|
Parameters:
|
|
|
|
None
|
|
|
|
This function will return:
|
|
|
|
A null-terminated string describing this DLL.
|
|
*/
|
|
char *mpidbg_version_string(void);
|
|
|
|
/*-----------------------------------------------------------------------*/
|
|
|
|
/* Returns the address width that this DLL was compiled with.
|
|
|
|
Parameters:
|
|
|
|
None
|
|
|
|
This function will return:
|
|
|
|
sizeof(mqs_taddr_t)
|
|
*/
|
|
|
|
int mpidbg_dll_taddr_width(void);
|
|
|
|
/*-----------------------------------------------------------------------*/
|
|
|
|
/* Setup debug information for a specific image, this must save the
|
|
callbacks (probably in the mqs_image_info), and use those functions
|
|
for accessing this image.
|
|
|
|
The DLL should use the mqs_put_image_info and mqs_get_image_info
|
|
functions to associate whatever information it wants to keep with
|
|
the image (e.g., all of the type offsets it needs could be kept
|
|
here). The debugger will call mqs_destroy_image_info when it no
|
|
longer wants to keep information about the given executable.
|
|
|
|
This will be called once for each executable image in the parallel
|
|
job.
|
|
|
|
Parameters:
|
|
|
|
IN: image: the application image.
|
|
IN: callbacks: Table of pointers to the debugger image-specific
|
|
functions. The DLL need only save the pointer, the
|
|
debugger promises to maintain the table of functions
|
|
valid for as long as needed. The table remains the
|
|
property of the debugger, and should not be altered
|
|
or deallocated by the DLL. This applies to all of
|
|
the callback tables.
|
|
IN/OUT: handle_types: a pointer to a pre-allocated struct
|
|
containing mqs_types for each of the MPI
|
|
handle types. Must be filled in with results
|
|
from mqs_find_type for each MPI handle type.
|
|
|
|
This function will return:
|
|
|
|
MPIDBG_SUCCESS: if all initialization went well
|
|
MPIDBG_ERR_NOT_SUPPORTED: if the image does not support the MPIDBG
|
|
interface. In this case, no other mpidbg functions
|
|
will be invoked on this image (not even
|
|
mpidbg_finalize_per_image()).
|
|
MPIDBG_ERR_*: if something went wrong.
|
|
*/
|
|
int mpidbg_init_per_image(mqs_image *image,
|
|
const mqs_image_callbacks *callbacks,
|
|
struct mpidbg_handle_info_t *handle_types);
|
|
|
|
/* This function will be called once when an application image that
|
|
previously had mpidbg_init_per_image() successfully invoked that is
|
|
now ending (e.g., the debugger is exiting, the debugger has
|
|
unloaded this image, etc.). This function can be used to clean up
|
|
any image-specific data.
|
|
|
|
Parameters:
|
|
|
|
IN: image: the application image.
|
|
IN: image_info: the info associated with the application image.
|
|
*/
|
|
void mpidbg_finalize_per_image(mqs_image *image, mqs_image_info *image_info);
|
|
|
|
/*-----------------------------------------------------------------------*/
|
|
|
|
/* This function will only be called if mpidbg_init_per_image()
|
|
returned successfully, indicating that the image contains
|
|
information for MPI handle information. If you cannot tell whether
|
|
a process will have MPI handle information in it by examining the
|
|
image, you should return SUCCESS from mpidbg_init_per_image() and
|
|
use this function to check whether MPI handle information is
|
|
available in the process.
|
|
|
|
Set up whatever process specific information we need. For instance,
|
|
addresses of global variables should be handled here rather than in
|
|
the image information, because if data may be in dynamic libraries
|
|
which could end up mapped differently in different processes.
|
|
|
|
Note that certain global variables are not valid until after this
|
|
call completes successfully (see above; e.g.,
|
|
mpidbg_comm_capabilities, mpidbg_comm_name_mapping, etc.).
|
|
|
|
Parameters:
|
|
|
|
IN: process: the process
|
|
IN: callbacks: Table of pointers to the debugger process-specific
|
|
functions. The DLL need only save the pointer, the
|
|
debugger promises to maintain the table of functions
|
|
valid for as long as needed. The table remains the
|
|
property of the debugger, and should not be altered
|
|
or deallocated by the DLL. This applies to all of
|
|
the callback tables.
|
|
IN/OUT: handle_types: the same handle_types that was passed to
|
|
mqs_init_per_image. It can be left unaltered
|
|
if the results from mqs_init_per_image were
|
|
sufficient, or modified if necessary to be
|
|
specific to this process.
|
|
|
|
This function will return:
|
|
|
|
MPIDBG_SUCCESS: if all initialization went well
|
|
MPIDBG_ERR_NOT_SUPPORTED: if the process does not support the MPIDBG
|
|
interface. In this case, no other mpidbg functions
|
|
will be invoked on this image (not even
|
|
mpidbg_finalize_per_process()).
|
|
MPIDBG_ERR_*: if something went wrong.
|
|
*/
|
|
int mpidbg_init_per_process(mqs_process *process,
|
|
const mqs_process_callbacks *callbacks,
|
|
struct mpidbg_handle_info_t *handle_types);
|
|
|
|
/* This function will be called once when an application image that
|
|
previously had mpidbg_init_per_process() successfully invoked that
|
|
is now ending (e.g., the debugger is exiting, the debugger has
|
|
stopped executing this process, etc.). This function can be used
|
|
to clean up any process-specific data.
|
|
|
|
Parameters:
|
|
|
|
IN: process: the application process.
|
|
IN: process_info: the info associated with the application process.
|
|
*/
|
|
void mpidbg_finalize_per_process(mqs_process *process,
|
|
mqs_process_info *process_info);
|
|
|
|
/*-----------------------------------------------------------------------
|
|
* MPI handle query functions
|
|
* MPI_Comm
|
|
*-----------------------------------------------------------------------*/
|
|
|
|
/* Query a specific MPI_Comm handle and, if found and valid, allocate
|
|
a new instance of the mpidbg_comm_info_t struct and all of its
|
|
internal data, and fill it in with information about the underlying
|
|
corresponding MPI communicator object.
|
|
|
|
Parameters:
|
|
|
|
IN: image: image
|
|
IN: image_info: image info that was previously "put"
|
|
IN: process: process
|
|
IN: process_info: process info that was previously "put"
|
|
IN: comm: communicator handle
|
|
OUT: info: pointer to be filled with a newly-allocated struct
|
|
mpidbg_comm_info_t
|
|
|
|
This function will return:
|
|
|
|
MPIDBG_SUCCESS: if the handle is valid, was found, and the info
|
|
parameter was filled in successfully.
|
|
MPIDBG_ERR_NOT_FOUND: if the handle is not valid / found.
|
|
MPIDBG_ERR_UNSUPPORTED: if this function is unsupported.
|
|
*/
|
|
int mpidbg_comm_query(mqs_image *image, mqs_image_info *image_info,
|
|
mqs_process *process, mqs_process_info *process_info,
|
|
mqs_taddr_t c_comm, struct mpidbg_comm_info_t **info);
|
|
|
|
/* Query function to turn a Fortran INTEGER handle into its equivalent
|
|
C handle (that can then be queried with mpidbg_comm_query()).
|
|
mqs_taddr_t is used in order to guarantee to be large enough to
|
|
hold a Fortran INTEGER.
|
|
|
|
Parameters:
|
|
|
|
IN: image: image
|
|
IN: image_info: image info that was previously "put"
|
|
IN: process: process
|
|
IN: process_info: process info that was previously "put"
|
|
IN: f77_comm: a zero-padded Fortran integer containing the Fortran
|
|
handle of the communicator.
|
|
OUT: c_comm: a C handle suitable to pass to mpidbg_comm_query().
|
|
|
|
This function returns:
|
|
|
|
MPIDBG_SUCCESS: if the handle is valid, was found, and the c_comm
|
|
parameter was filled in successfully.
|
|
MPIDBG_ERR_NOT_FOUND: if the handle is not valid / found.
|
|
MPIDBG_ERR_UNSUPPORTED: if this function is unsupported.
|
|
*/
|
|
int mpidbg_comm_f2c(mqs_image *image, mqs_image_info *image_info,
|
|
mqs_process *process, mqs_process_info *process_info,
|
|
mqs_taddr_t f77_comm, mqs_taddr_t *c_comm);
|
|
|
|
/* Query function to turn a C++ handle into its equivalent C handle
|
|
(that can then be queried with mpidbg_comm_query()). Pass the
|
|
pointer to the object as the cxx_comm (because we can't pass the
|
|
object itself); we return the C handle.
|
|
|
|
--> JMS Need more discussion here -- George has some opinion. He
|
|
thinks we don't need this.
|
|
Parameters:
|
|
|
|
IN: image: image
|
|
IN: image_info: image info that was previously "put"
|
|
IN: process: process
|
|
IN: process_info: process info that was previously "put"
|
|
IN: cxx_comm: a pointer to the MPI handle object
|
|
IN: comm_type: one of 0, MPIDBG_COMM_INFO_CARTESION,
|
|
MPIDBG_COMM_INFO_GRAPH, or
|
|
MPIDBG_COMM_INFO_INTERCOMM indicating whether the
|
|
object is an MPI::Comm, MPI::Cartcomm,
|
|
MPI::Graphcomm, or MPI::Intercomm.
|
|
OUT: c_comm: a C handle suitable to pass to mpidbg_comm_query().
|
|
|
|
This function returns:
|
|
|
|
MPIDBG_SUCCESS: if the handle is valid, was found, and the c_comm
|
|
parameter was filled in successfully.
|
|
MPIDBG_ERR_NOT_FOUND: if the handle is not valid / found.
|
|
MPIDBG_ERR_UNSUPPORTED: if this function is unsupported.
|
|
*/
|
|
int mpidbg_comm_cxx2c(mqs_image *image, mqs_image_info *image_info,
|
|
mqs_process *process, mqs_process_info *process_info,
|
|
mqs_taddr_t cxx_comm,
|
|
enum mpidbg_comm_info_bitmap_t comm_type,
|
|
mqs_taddr_t *c_comm);
|
|
|
|
/*-----------------------------------------------------------------------
|
|
* MPI handle query functions
|
|
* MPI_Errhandler
|
|
*-----------------------------------------------------------------------*/
|
|
|
|
/* These functions are analogous to the mpidbg_comm_* functions, but
|
|
for MPI_Errhandler. Note that there is no need for a
|
|
"errhandler_type" argument to the cxx2c function because
|
|
MPI::Errhandler has no derived classes. */
|
|
|
|
int mpidbg_errhandler_query(mqs_image *image, mqs_image_info *image_info,
|
|
mqs_process *process, mqs_process_info *process_info,
|
|
mqs_taddr_t errhandler,
|
|
struct mpidbg_errhandler_info_t **info);
|
|
int mpidbg_errhandler_f2c(mqs_image *image, mqs_image_info *image_info,
|
|
mqs_process *process, mqs_process_info *process_info,
|
|
mqs_taddr_t f77_errhandler,
|
|
mqs_taddr_t *c_errhandler);
|
|
int mpidbg_errhandler_cxx2c(mqs_image *image, mqs_image_info *image_info,
|
|
mqs_process *process, mqs_process_info *process_info,
|
|
mqs_taddr_t cxx_errhandler,
|
|
mqs_taddr_t *c_errhandler);
|
|
|
|
/*-----------------------------------------------------------------------
|
|
* MPI handle query functions
|
|
* MPI_Request
|
|
*-----------------------------------------------------------------------*/
|
|
|
|
/* These functions are analogous to the mpidbg_comm_* functions, but
|
|
for MPI_Request. */
|
|
|
|
int mpidbg_request_query(mqs_image *image, mqs_image_info *image_info,
|
|
mqs_process *process, mqs_process_info *process_info,
|
|
mqs_taddr_t request,
|
|
struct mpidbg_request_info_t **info);
|
|
int mpidbg_request_f2c(mqs_image *image, mqs_image_info *image_info,
|
|
mqs_process *process, mqs_process_info *process_info,
|
|
mqs_taddr_t f77_request, mqs_taddr_t *c_request);
|
|
int mpidbg_request_cxx2c(mqs_image *image, mqs_image_info *image_info,
|
|
mqs_process *process, mqs_process_info *process_info,
|
|
mqs_taddr_t cxx_request,
|
|
enum mpidbg_request_info_bitmap_t request_type,
|
|
mqs_taddr_t *c_request);
|
|
|
|
/*-----------------------------------------------------------------------
|
|
* MPI handle query functions
|
|
* MPI_Status
|
|
*-----------------------------------------------------------------------*/
|
|
|
|
/* These functions are analogous to the mpidbg_comm_* functions, but
|
|
for MPI_Status. */
|
|
|
|
int mpidbg_status_query(mqs_image *image, mqs_image_info *image_info,
|
|
mqs_process *process, mqs_process_info *process_info,
|
|
mqs_taddr_t status,
|
|
struct mpidbg_status_info_t **info);
|
|
int mpidbg_status_f2c(mqs_image *image, mqs_image_info *image_info,
|
|
mqs_process *process, mqs_process_info *process_info,
|
|
mqs_taddr_t f77_status, mqs_taddr_t *c_status);
|
|
int mpidbg_status_cxx2c(mqs_image *image, mqs_image_info *image_info,
|
|
mqs_process *process, mqs_process_info *process_info,
|
|
mqs_taddr_t cxx_status,
|
|
mqs_taddr_t *c_status);
|
|
|
|
#endif /* __MPIDBG_INTERFACE_H__ */
|