openmpi/ompi/debuggers/mpihandles_interface.h

/*
 * 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__ */