mpi_interface.h

fortran并行计算包

/* -*- Mode: C; c-basic-offset:4 ; -*- */
/**********************************************************************
 * Copyright (C) 2000 Etnus, LLC
 *
 * Permission is hereby granted to use, reproduce, prepare derivative
 * works, and to redistribute to others.
 *
 *				  DISCLAIMER
 *
 * Neither Etnus, nor any of their employees, makes any warranty
 * express or implied, or assumes any legal liability or
 * responsibility for the accuracy, completeness, or usefulness of any
 * information, apparatus, product, or process disclosed, or
 * represents that its use would not infringe privately owned rights.
 *
 * This code was written by
 * James Cownie: Etnus, LLC. <[e-mail]>
 **********************************************************************/

/**********************************************************************
 * Copyright (C) 1997-1998 Dolphin Interconnect Solutions Inc.
 *
 * Permission is hereby granted to use, reproduce, prepare derivative
 * works, and to redistribute to others.
 *
 *				  DISCLAIMER
 *
 * Neither Dolphin Interconnect Solutions, nor any of their employees,
 * makes any warranty express or implied, or assumes any legal
 * liability or responsibility for the accuracy, completeness, or
 * usefulness of any information, apparatus, product, or process
 * disclosed, or represents that its use would not infringe privately
 * owned rights.
 *
 * This code was written by
 * James Cownie: Dolphin Interconnect Solutions. <[e-mail]>
 **********************************************************************/


/* Update log
 *
 * Oct  6 2000 JHC: Add all of the MPI-2 relevant types and functions.
 *              This does need a compatibility number change to 
 *              ensure new libraries can't get loaded into old debuggers.
 *              New debuggers can continue to use old libraries, though.
 *              New functions under control of FOR_MPI2
 * Oct  2 2000 JHC: Add the mqs_get_comm_group function to support
 *              partial acquisition.
 * Mar 21 2000 JHC: Lower the version compatibility again, but add
 *              a new DLL provided call to tell us the width it
 *              believes mqs_taddr_t is. If the DLL doesn't provide this
 *              call, we assume it's old and use the appropriate old width.
 *              This lets us gracefully handle widening the interface on AIX.
 * Mar 17 2000 JHC: Add FORCE_32BIT_MPI conditional compilation flag.
 * Mar  3 2000 JHC: Widen the tword_t and taddr_t on AIX, now that IBM
 *              has 64 bit machines. Increment the version compatibility
 *              number on AIX (only) since this is an incompatible change in 
 *              the interface.
 * Oct  1 1998 JHC: Change MQS_INVALID_PROCESS to -1, TV would never generate
 *              the old value anyway.
 * May 26 1998 JHC: Change interface compatibility, add extra strings in the
 *              mqs_pending_operation.
 * Apr 23 1998 JHC: Make mqs_tword_t and mqs_taddr_t into 64 bit entities on
 *              SGI. Expand the comment above their definition.
 * Mar  9 1998 JHC: Added mqs_sizeof_ft. Of course we always needed this !
 * Nov  6 1997 JHC: Worked over somewhat to keep John happy :-)
 * Oct 27 1997 James Cownie <[e-mail]>: Created.
 */

/***********************************************************************
 * This header file defines the interface between a debugger and a
 * dynamically loaded library use to implement access to MPI message
 * queues.
 *
 * The interface is specified at the C level, to avoid C++ compiler issues.
 *
 * The interface allows code in the DLL to 
 * 1) find named types from the debugger's type system and look up fields in them
 * 2) find the address of named external variables 
 * 3) access objects at absolute addresses in the target process.
 * 4) convert objects from target format to host format.
 *
 * A number of different objects are passed backwards and forwards
 * between the debugger and the DLL :-
 *
 * executable images
 * processes
 * communicators
 *
 * Many of these are opaque to the DLL, in such cases they will be
 * defined in the interface as pointers to opaque structures, since
 * this provides type checking while maintaining information hiding.
 *
 * All named entities in here start with the prefix "mqs_" (for
 * Message Queue Support), all the debugger callbacks are made via 
 * callback tables, so the real (linkage) names of the functions are
 * not visible to the DLL.
 */

#ifndef _MPI_INTERFACE_INCLUDED
#define _MPI_INTERFACE_INCLUDED

#include <stdio.h>				/* For FILENAME_MAX */

#ifdef	__cplusplus
extern "C" {
#endif

/***********************************************************************
 * Version of the interface this header represents 
 */
enum
{
#if defined(FOR_MPI2)
  MQS_INTERFACE_COMPATIBILITY = 3		/* Has MPI-2 functions */
#else
  MQS_INTERFACE_COMPATIBILITY = 2
#endif
};

/***********************************************************************
 * type definitions.
 */

/* Opaque types are used here to provide a degree of type checking
 * through the prototypes of the interface functions.
 *
 * Only pointers to these types are ever passed across the interface.
 * Internally to the debugger, or the DLL you should immediately cast
 * these pointers to pointers to the concrete types that you actually
 * want to use.
 *
 * (An alternative would be to use void * for all of these arguments,
 * but that would remove a useful degree of type checking, assuming
 * that you are thinking while typing the casts :-)
 */

/* Types which will be (cast to) concrete types in the DLL */
typedef struct _mqs_image_info   mqs_image_info;
typedef struct _mqs_process_info mqs_process_info;
#if defined(FOR_MPI2)
typedef struct _mqs_job_info     mqs_job_info;
#endif

/* Types which will be (cast to) concrete types in the debugger */
typedef struct mqs_image_    mqs_image;
#if defined(FOR_MPI2)
typedef struct mqs_job_      mqs_job;
#endif
typedef struct mqs_process_  mqs_process;
typedef struct mqs_type_     mqs_type;

/* *** BEWARE ***
 * On machines with two pointer lengths (such as SGI -n32, -64 compilations,
 * and AIX and Solaris soon), it is quite likely that TotalView and the DLL
 * will have been compiled with the 32 bit model, *but* will need to debug
 * code compiled with the 64 bit one. The mqs_taddr_t and mqs_tword_t need
 * to be a type which even when compiled with the 32 bit model compiler can
 * hold the longer (64 bit) pointer.
 *
 * You may need to add your host to this #if, if you have a machine with
 * two compilation models.
 * *** END BEWARE ***
 *
 * It would be better not to have this target dependence in the
 * interface, but it is unreasonable to require a 64 bit interface on
 * 32 bit machines, and we need the 64 bit interface in some places.
 */

#if !defined (FORCE_32BIT_MPI) && (defined (__sgi) || defined (__hpux) || defined (_AIX))
typedef unsigned long long mqs_taddr_t;		/* Something long enough for a target address */
typedef long long          mqs_tword_t;		/* Something long enough for a word    */
#else
typedef unsigned long mqs_taddr_t;		/* Something long enough for a target address */
typedef long          mqs_tword_t;		/* Something long enough for a word    */
#endif

/***********************************************************************
 * Defined structures which form part of the interface.
 */

/* A structure for (target) architectural information */
typedef struct
{
  int short_size;				/* sizeof (short) */
  int int_size;					/* sizeof (int)   */
  int long_size;				/* sizeof (long)  */
  int long_long_size;				/* sizeof (long long) */
  int pointer_size;				/* sizeof (void *) */
} mqs_target_type_sizes;
  
/* Result codes. 
 * mqs_ok is returned for success. 
 * Anything else implies a failure of some sort. 
 *
 * Most of the functions actually return one of these, however to avoid
 * any potential issues with different compilers implementing enums as
 * different sized objects, we actually use int as the result type.
 *
 * Note that both the DLL and the debugger will use values starting at
 * mqs_first_user_code, since you always know which side you were calling,
 * this shouldn't be a problem.
 *
 * See below for functions to convert codes to strings.
 */
enum {
  mqs_ok = 0,
  mqs_no_information,
  mqs_end_of_list,
  mqs_first_user_code = 100			/* Allow for more pre-defines */
};

#if defined(FOR_MPI2)
/* For handling attachment to new processes in MPI-2 we need to know
 * where they are.
 */
typedef struct mqs_process_location {
  long pid;
  char image_name [FILENAME_MAX];
  char host_name  [64];
} mqs_process_location;
#endif

/* Languages */
typedef enum {
  mqs_lang_c     = 'c',
  mqs_lang_cplus = 'C',
  mqs_lang_f77   = 'f',
  mqs_lang_f90   = 'F'
} mqs_lang_code;

/* Which queue are we interested in ? */
typedef enum
{
  mqs_pending_sends, 
  mqs_pending_receives, 
  mqs_unexpected_messages
} mqs_op_class;

/* A value to represent an invalid process index. */
enum
{
  MQS_INVALID_PROCESS = -1
};

enum mqs_status 
{
  mqs_st_pending, mqs_st_matched, mqs_st_complete
};

/* A structure to represent a communicator */
typedef struct
{
  mqs_taddr_t unique_id;			/* A unique tag for the communicator */
  mqs_tword_t local_rank;			/* The rank of this process Comm_rank */
  mqs_tword_t size;				/* Comm_size  */
  char    name[64];				/* the name if it has one */
} mqs_communicator;

/*
 * We currently assume that all messages are flattened into contiguous buffers.
 * This is potentially incorrect, but let's leave that complication for a while.
 */

typedef struct
{
  /* Fields for all messages */
  int status;					/* Status of the message (really enum mqs_status) */
  mqs_tword_t desired_local_rank;		/* Rank of target/source -1 for ANY */
  mqs_tword_t desired_global_rank;		/* As above but in COMM_WORLD  */
  int tag_wild;					/* Flag for wildcard receive  */
  mqs_tword_t desired_tag;			/* Only if !tag_wild */
  mqs_tword_t desired_length;			/* Length of the message buffer */
  int system_buffer;				/* Is it a system or user buffer ? */
  mqs_taddr_t buffer;				/* Where data is */

  /* Fields valid if status >= matched or it's a send */
  mqs_tword_t actual_local_rank;		/* Actual local rank */
  mqs_tword_t actual_global_rank;		/* As above but in COMM_WORLD */
  mqs_tword_t actual_tag;				
  mqs_tword_t actual_length;
  
  /* Additional strings which can be filled in if the DLL has more
   * info.  (Uninterpreted by the debugger, simply displayed to the
   * user).  
   *
   * Can be used to give the name of the function causing this request,
   * for instance.
   *
   * Up to five lines each of 64 characters.
   */
  char extra_text[5][64];
} mqs_pending_operation;

/***********************************************************************
 * Callbacks from the DLL into the debugger.
 ***********************************************************************
 * These are all made via a table of function pointers.
 */

/* Hang information on the image */
typedef void (*mqs_put_image_info_ft) (mqs_image *, mqs_image_info *);
/* Get it back */
typedef mqs_image_info * (*mqs_get_image_info_ft) (mqs_image *);

#if defined(FOR_MPI2)
/* Given a job and an index return the process object */
typedef mqs_process * (*mqs_get_process_ft) (mqs_job *, int);