OpenMPI  0.1.1
mpihandles_interface.h
1 /*
2  * Copyright (c) 2007 High Performance Computing Center Stuttgart,
3  * University of Stuttgart. All rights reserved.
4  * Copyright (c) 2007-2008 Cisco Systems, Inc. All rights reserved.
5  * Copyright (c) 2007 The University of Tennessee and The University of
6  * Tennessee Research Foundation. All rights reserved.
7  * $COPYRIGHT$
8  *
9  * Additional copyrights may follow
10  *
11  * Some text copied from and references made to mpi_interface.h.
12  *
13  * Copyright (C) 2000-2004 by Etnus, LLC
14  * Copyright (C) 1999 by Etnus, Inc.
15  * Copyright (C) 1997-1998 Dolphin Interconnect Solutions Inc.
16  *
17  * $HEADER$
18  */
19 
20 #ifndef __MPIDBG_INTERFACE_H__
21 #define __MPIDBG_INTERFACE_H__ 1
22 
23 #include "ompi_config.h"
24 
25 /*
26  * This file provides interface functions for a debugger to gather
27  * additional information about MPI handles.
28  */
29 #include <sys/types.h>
30 
31 /* Include the Etnus debugger message queue interface so that we can
32  use much of its infrastructure (e.g., the mqs_basic_callbacks,
33  mqs_image_callbacks, and mqs_process_callbacks). */
34 #define FOR_MPI2 0
35 #include "msgq_interface.h"
36 
37 /**************************************************************************
38  * Types and macros
39  **************************************************************************/
40 
41 enum {
42  MPIDBG_MAX_OBJECT_NAME = MPI_MAX_OBJECT_NAME
43 };
44 enum {
45  MPIDBG_MAX_FILENAME = 1024
46 };
47 enum {
48  MPIDBG_INTERFACE_VERSION = 1
49 };
50 
51 
52 /*-----------------------------------------------------------------------
53  * Global initialization information for the DLL
54  *-----------------------------------------------------------------------*/
55 
56 /* Structure containing types for C and C++ MPI handles */
58  /* C handle types. They are typically pointers to something or
59  integers. */
60  /* Back-end type for MPI_Aint */
61  mqs_type *hi_c_aint;
62  /* Back-end type for MPI_Comm */
63  mqs_type *hi_c_comm;
64  /* Back-end type for MPI_Datatype */
65  mqs_type *hi_c_datatype;
66  /* Back-end type for MPI_Errhandler */
67  mqs_type *hi_c_errhandler;
68  /* Back-end type for MPI_File */
69  mqs_type *hi_c_file;
70  /* Back-end type for MPI_Group */
71  mqs_type *hi_c_group;
72  /* Back-end type for MPI_Info */
73  mqs_type *hi_c_info;
74  /* Back-end type for MPI_Offset */
75  mqs_type *hi_c_offset;
76  /* Back-end type for MPI_Op */
77  mqs_type *hi_c_op;
78  /* Back-end type for MPI_Request */
79  mqs_type *hi_c_request;
80  /* Back-end type for MPI_Status */
81  mqs_type *hi_c_status;
82  /* Back-end type for MPI_Win */
83  mqs_type *hi_c_win;
84 
85  /* C++ handle types. Note that these will always be *objects*,
86  never pointers. */
87  /* Back-end type for MPI::Aint */
88  mqs_type *hi_cxx_aint;
89  /* Back-end type for MPI::Comm */
90  mqs_type *hi_cxx_comm;
91  /* Back-end type for MPI::Intracomm */
92  mqs_type *hi_cxx_intracomm;
93  /* Back-end type for MPI::Intercomm */
94  mqs_type *hi_cxx_intercomm;
95  /* Back-end type for MPI::Graphcomm */
96  mqs_type *hi_cxx_graphcomm;
97  /* Back-end type for MPI::Cartcomm */
98  mqs_type *hi_cxx_cartcomm;
99  /* Back-end type for MPI::Datatype */
100  mqs_type *hi_cxx_datatype;
101  /* Back-end type for MPI::Errhandler */
102  mqs_type *hi_cxx_errhandler;
103  /* Back-end type for MPI::File */
104  mqs_type *hi_cxx_file;
105  /* Back-end type for MPI::Group */
106  mqs_type *hi_cxx_group;
107  /* Back-end type for MPI::Info */
108  mqs_type *hi_cxx_info;
109  /* Back-end type for MPI::Offset */
110  mqs_type *hi_cxx_offset;
111  /* Back-end type for MPI::Op */
112  mqs_type *hi_cxx_op;
113  /* Back-end type for MPI::Request */
114  mqs_type *hi_cxx_request;
115  /* Back-end type for MPI::Prequest */
116  mqs_type *hi_cxx_prequest;
117  /* Back-end type for MPI::Grequest */
118  mqs_type *hi_cxx_grequest;
119  /* Back-end type for MPI::Status */
120  mqs_type *hi_cxx_status;
121  /* Back-end type for MPI::Win */
122  mqs_type *hi_cxx_win;
123 };
124 
125 enum mpidbg_return_codes_t {
126  /* Success */
127  MPIDBG_SUCCESS,
128  /* Something was not found */
129  MPIDBG_ERR_NOT_FOUND,
130  /* Something is not supported */
131  MPIDBG_ERR_NOT_SUPPORTED,
132  /* Something is out of range */
133  MPIDBG_ERR_OUT_OF_RANGE,
134  /* Something is not available */
135  MPIDBG_ERR_UNAVAILABLE,
136  /* Ran out of memory */
137  MPIDBG_ERR_NO_MEM,
138  /* Sentinel max value */
139  MPIDBG_MAX_RETURN_CODE
140 };
141 
142 /*-----------------------------------------------------------------------
143  * General data structures
144  *-----------------------------------------------------------------------*/
145 
146 /* Information about MPI processes */
148  /* JMS: need something to uniquely ID MPI processes in the
149  presence of MPI_COMM_SPAWN */
150 
151  /* Global rank in MPI_COMM_WORLD */
152  int mpi_comm_world_rank;
153 };
154 /* ==> JMS Should we just use mqs_process_location instead? George
155  thinks that this is unncessary -- perhaps due to the fact that we
156  could use mqs_process_location...? Need to get some feedback from
157  others on this one. Need to check Euro PVM/MPI '06 paper... */
158 
159 /* General name -> handle address mappings. This is an optional type
160  that is used to describe MPI's predefined handles if the
161  pre-defined names do not appear as symbols in the MPI process.
162  E.g., if MPI_COMM_WORLD is a #define that maps to some other value,
163  this data structure can be used to map the string "MPI_COMM_WORLD"
164  to the actual value of the handle that it corresponds to (e.g., 0
165  or a pointer value). */
167  /* Name of the handle */
168  char *map_name;
169 
170  /* Handle that the name corresponds to. Will be 0/NULL if there
171  is no corresponding back-end object. */
172  mqs_taddr_t map_handle;
173 };
174 
175 /* MPI attribute / value pairs. Include both a numeric and string
176  key; pre-defined MPI keyvals (e.g., MPI_TAG_MAX) have a
177  human-readable string name. The string will be NULL for
178  non-predefined keyvals. */
180  /* Keyval */
181  int keyval;
182  /* Keyval name; will be non-NULL for attributes that have a
183  human-readable name (e.g., MPI predefined keyvals) */
184  char *keyval_name;
185  /* Value */
186  char *value;
187 };
188 
189 /*-----------------------------------------------------------------------
190  * Communicators
191  *-----------------------------------------------------------------------*/
192 
193 /* Using an enum instead of #define because debuggers can show the
194  *names* of enum values, not just the values. */
195 enum mpidbg_comm_capabilities_t {
196  /* Whether this MPI DLL supports returning basic information about
197  communicators */
198  MPIDBG_COMM_CAP_BASIC = 0x01,
199  /* Whether this MPI DLL supports returning names of
200  communicators */
201  MPIDBG_COMM_CAP_STRING_NAMES = 0x02,
202  /* Whether this MPI DLL supports indicating whether a communicator
203  has been freed by the user application */
204  MPIDBG_COMM_CAP_FREED_HANDLE = 0x04,
205  /* Whether this MPI DLL supports indicating whether a communicator
206  object has been freed by the MPI implementation or not */
207  MPIDBG_COMM_CAP_FREED_OBJECT = 0x08,
208  /* Whether this MPI DLL supports returning the list of MPI request
209  handles that are pending on a communicator */
210  MPIDBG_COMM_CAP_REQUEST_LIST = 0x10,
211  /* Whether this MPI DLL supports returning the list of MPI window
212  handles that were derived from a given communicator */
213  MPIDBG_COMM_CAP_WINDOW_LIST = 0x20,
214  /* Whether this MPI DLL supports returning the list of MPI file
215  handles that were derived from a given communicator */
216  MPIDBG_COMM_CAP_FILE_LIST = 0x40,
217  /* Sentinel max value */
218  MPIDBG_COMM_CAP_MAX
219 };
220 
221 enum mpidbg_comm_info_bitmap_t {
222  /* Predefined communicator if set (user-defined if not set) */
223  MPIDBG_COMM_INFO_PREDEFINED = 0x01,
224  /* Whether this communicator is a cartesian communicator or not
225  (mutually exclusive with _GRAPH and _INTERCOMM) */
226  MPIDBG_COMM_INFO_CARTESIAN = 0x02,
227  /* Whether this communicator is a graph communicator or not
228  (mutually exclusive with _CARTESIAN and _INTERCOMM) */
229  MPIDBG_COMM_INFO_GRAPH = 0x04,
230  /* If a cartesian or graph communicator, whether the processes in
231  this communicator were re-ordered when the topology was
232  assigned. */
233  MPIDBG_COMM_INFO_TOPO_REORDERED = 0x08,
234  /* Whether this is an intercommunicator or not (this communicator
235  is an intracommunicator if this flag is not yet). */
236  MPIDBG_COMM_INFO_INTERCOMM = 0x10,
237  /* This communicator has been marked for freeing by the user
238  application if set */
239  MPIDBG_COMM_INFO_FREED_HANDLE = 0x20,
240  /* This communicator has actually been freed by the MPI
241  implementation if set */
242  MPIDBG_COMM_INFO_FREED_OBJECT = 0x40,
243  /* The queried communicator is MPI_COMM_NULL */
244  MPIDBG_COMM_INFO_COMM_NULL = 0x80,
245  /* Sentinel max value */
246  MPIDBG_COMM_INFO_MAX
247 };
248 
250  /* Name of the MPI_COMM */
251  char comm_name[MPIDBG_MAX_OBJECT_NAME];
252 
253  /* Bit flags describing the communicator */
254  enum mpidbg_comm_info_bitmap_t comm_bitflags;
255 
256  /* This process' rank within this communicator */
257  int comm_rank;
258  /* The communicator's size */
259  int comm_size;
260 
261  /* Number of processes in the local group */
262  int comm_num_local_procs;
263  /* Information about each process in the local group (in
264  communicator rank order, length: comm_num_local_procs) */
265  struct mpidbg_process_t *comm_local_procs;
266 
267  /* For intercommunicators, the number of processes in the remote
268  group */
269  int comm_num_remote_procs;
270  /* For intercommunicators, information about each process in the
271  remote group (in communicator rank order, length:
272  comm_num_remote_procs) */
273  struct mpidbg_process_t *comm_remote_procs;
274 
275  /* For cartesian communicators, the number of dimensions */
276  int comm_cart_num_dims;
277  /* For cartesian communicators, an array of dimension lengths
278  (length: cart_comm_num_dims) */
279  int *comm_cart_dims;
280  /* For cartesian communicators, an array of boolean values
281  indicating whether each dimension is periodic or not (length:
282  cart_comm_num_dims) */
283  int8_t *comm_cart_periods;
284 
285  /* For graph communicators, the number of nodes */
286  int comm_graph_num_nodes;
287  /* For graph communicators, an array of the node degrees (length:
288  comm_graph_num_nodes) */
289  int *comm_graph_index;
290  /* For graph communicators, an array of the edges (length:
291  comm_graph_num_nodes) */
292  int *comm_graph_edges;
293 
294  /* C handle */
295  mqs_taddr_t comm_c_handle;
296  /* Fortran handle; will be MPIDBG_ERR_UNAVAILABLE if currently
297  unavailable or MPIDBG_ERR_NOT_SUPPORTED if not supported */
298  int comm_fortran_handle;
299 
300  /* Number of attributes defined on this communicator */
301  int comm_num_attrs;
302  /* Array of attribute keyval/value pairs defined on this
303  communicator (length: comm_num_attrs) */
304  struct mpidbg_attribute_pair_t *comm_attrs;
305 
306  /* Number of ongoing requests within this communicator, or
307  MPIDBG_ERR_NOT_SUPPORTED */
308  int comm_num_pending_requests;
309  /* If comm_num_pending_requests != MPIDBG_ERR_NOT_SUPPORTED, an
310  array of ongoing request handles attached on this
311  communicator (length: comm_num_pending_requests) */
312  mqs_taddr_t *comm_pending_requests;
313 
314  /* Number of MPI windows derived from this communicator, or
315  MPIDBG_ERR_NOT_SUPPORTED */
316  int comm_num_derived_windows;
317  /* If comm_num_derived_windows != MPIDBG_ERR_NOT_SUPPORTED, an
318  array of window handles derived from this communicator (length:
319  com_num_derived_windows) */
320  mqs_taddr_t *comm_derived_windows;
321 
322  /* Number of MPI files derived from this communicator, or
323  MPIDBG_ERR_NOT_SUPPORTED */
324  int comm_num_derived_files;
325  /* If comm_num_derived_files != MPIDBG_ERR_NOT_SUPPORTED, an array
326  of file handles derived from this communicator (length:
327  comm_num_derived_files) */
328  mqs_taddr_t *comm_derived_files;
329 };
330 
331 
332 /*-----------------------------------------------------------------------
333  * Requests
334  *-----------------------------------------------------------------------*/
335 
336 /* Using an enum instead of #define because debuggers can show the
337  *names* of enum values, not just the values. */
338 enum mpidbg_request_capabilities_t {
339  /* Whether this MPI DLL supports returning basic information about
340  requests */
341  MPIDBG_REQUEST_CAP_BASIC = 0x01,
342  /* Sentinel max value */
343  MPIDBG_REQUEST_CAP_MAX
344 };
345 
346 enum mpidbg_request_info_bitmap_t {
347  /* Predefined request if set (user-defined if not set) */
348  MPIDBG_REQUEST_INFO_PREDEFINED = 0x01,
349  /* Sentinel max value */
350  MPIDBG_REQUEST_INFO_MAX
351 };
352 
354  /* Bit flags describing the error handler */
355  enum mpidbg_request_info_bitmap_t req_bitflags;
356 
357  /* C handle */
358  mqs_taddr_t req_c_handle;
359  /* Fortran handle; will be MPIDBG_ERR_UNAVAILABLE if currently
360  unavailable or MPIDBG_ERR_NOT_SUPPORTED if not supported */
361  int req_fortran_handle;
362 };
363 
364 /*-----------------------------------------------------------------------
365  * Statuses
366  *-----------------------------------------------------------------------*/
367 
368 enum mpidbg_status_capabilities_t {
369  /* Whether this MPI DLL supports returning basic information about
370  statuses */
371  MPIDBG_STATUS_CAP_BASIC = 0x01,
372  /* Sentinel max value */
373  MPIDBG_STATUS_CAP_MAX
374 };
375 
376 enum mpidbg_status_info_bitmap_t {
377  /* Predefined status if set (user-defined if not set) */
378  MPIDBG_STATUS_INFO_PREDEFINED = 0x01,
379  /* Sentinel max value */
380  MPIDBG_STATUS_INFO_MAX
381 };
382 
384  /* Bit flags describing the error handler */
385  enum mpidbg_status_info_bitmap_t status_bitflags;
386 };
387 
388 /*-----------------------------------------------------------------------
389  * Error handlers
390  *-----------------------------------------------------------------------*/
391 
392 /* Using an enum instead of #define because debuggers can show the
393  *names* of enum values, not just the values. */
394 enum mpidbg_errhandler_capabilities_t {
395  /* Whether this MPI DLL supports returning basic information about
396  error handlers */
397  MPIDBG_ERRH_CAP_BASIC = 0x01,
398  /* Whether this MPI DLL supports returning names of the predefined
399  error handlers */
400  MPIDBG_ERRH_CAP_STRING_NAMES = 0x02,
401  /* Whether this MPI DLL supports indicating whether an error
402  handler has been freed by the user application */
403  MPIDBG_ERRH_CAP_FREED_HANDLE = 0x04,
404  /* Whether this MPI DLL supports indicating whether an error
405  handler object has been freed by the MPI implementation or
406  not */
407  MPIDBG_ERRH_CAP_FREED_OBJECT = 0x08,
408  /* Whether this MPI DLL supports returning the list of MPI handles
409  that an MPI error handler is attached to */
410  MPIDBG_ERRH_CAP_HANDLE_LIST = 0x10,
411  /* Sentinel max value */
412  MPIDBG_ERRH_CAP_MAX
413 };
414 
415 enum mpidbg_errhandler_info_bitmap_t {
416  /* Predefined error handler if set (user-defined if not set) */
417  MPIDBG_ERRH_INFO_PREDEFINED = 0x01,
418  /* Communicator error handler if set */
419  MPIDBG_ERRH_INFO_COMMUNICATOR = 0x02,
420  /* File error handler if set */
421  MPIDBG_ERRH_INFO_FILE = 0x04,
422  /* Window error handler if set */
423  MPIDBG_ERRH_INFO_WINDOW = 0x08,
424  /* Callback is in C if set (Fortran if not set) */
425  MPIDBG_ERRH_INFO_C_CALLBACK = 0x10,
426  /* This errorhandler has been marked for freeing by the user
427  application if set */
428  MPIDBG_ERRH_INFO_FREED_HANDLE = 0x20,
429  /* This errorhandler has actually been freed by the MPI
430  implementation if set */
431  MPIDBG_ERRH_INFO_FREED_OBJECT = 0x40,
432  /* Sentinel max value */
433  MPIDBG_ERRH_INFO_MAX
434 };
435 
437  /* String name; only relevant for predefined errorhandlers. If
438  not a predefined errorhandler, eh_name[0] will be '\0'; */
439  char eh_name[MPIDBG_MAX_OBJECT_NAME];
440 
441  /* Bit flags describing the error handler */
442  enum mpidbg_errhandler_info_bitmap_t eh_bitflags;
443 
444  /* C handle */
445  mqs_taddr_t eh_c_handle;
446  /* Fortran handle; will be MPIDBG_ERR_UNAVAILABLE if currently
447  unavailable or MPIDBG_ERR_NOT_SUPPORTED if not supported */
448  int eh_fortran_handle;
449 
450  /* Number of MPI handles that this error handler is attached to.
451  MPIDBG_ERR_NOT_SUPPORTED means that this information is not
452  supported by the DLL. */
453  int16_t eh_refcount;
454  /* If eh_refcount != MPIDBG_ERR_NOT_SUPPORTED, list of handles
455  that are using this error handler (length: eh_refcount). */
456  mqs_taddr_t *eh_handles;
457 
458  /* Address of the user-defined error handler (will be 0 for
459  predefined error handlers). Note that each of the 3 C
460  callbacks contain an MPI handle; the debugger will need to
461  figure out the appropriate size for these types depending on
462  the platform and MPI implementation. This value will be NULL
463  if MPIDBG_ERRH_INFO_PREDEFINED is set on the flags. */
464  mqs_taddr_t eh_callback_func;
465 };
466 
467 /**************************************************************************
468  * Global variables
469  *
470  * mpidbg_dll_locations is in the MPI application; all others are in
471  * the DLL.
472  **************************************************************************/
473 
474 /* Array of filenames instantiated IN THE MPI APPLICATION (*NOT* in
475  the DLL) that provides an set of locations where DLLs may be found.
476  The last pointer in the array will be a NULL sentinel value. The
477  debugger can scan the entries in the array, find one that matches
478  the debugger (by examining a) whether the dlopen works or not, and
479  b) if the dlopen succeeds, examine mpidbg_dll_is_big_endian and
480  mpidbg_dll_bitness), and try to dynamically open the dl_filename.
481  Notes:
482 
483  1. It is not an error if a dl_filename either does not exist or is
484  otherwise un-openable (the debugger can just try the next
485  match).
486  2. This array values are not valid until MPIR_Breakpoint.
487  3. If a filename is absolute, the debugger will attempt to load
488  exactly that. If the filename is relative, the debugger may try
489  a few prefix variations to find the DLL.
490  */
491 extern char **mpidbg_dll_locations;
492 
493 /* Global variable *in the DLL* describing whether this DLL is big or
494  little endian (1 = big endian, 0 = little endian). This value is
495  valid immediately upon opening of the DLL. */
496 extern char mpidbg_dll_is_big_endian;
497 
498 /* Global variable *in the DLL* describing the bitness of the DLL (8,
499  16, 32, 64, ...). This value is valid immediately upon opening of
500  the DLL. */
501 extern char mpidbg_dll_bitness;
502 
503 /* Global variable *in the DLL* describing the DLL's capabilties with
504  regards to communicators. This value is valid after a successfull
505  call to mpidbg_init_per_process(). */
506 extern enum mpidbg_comm_capabilities_t mpidbg_comm_capabilities;
507 
508 /* Global variable *in the DLL* that is an array of MPI communicator
509  handle names -> handle mappings (the last entry in the array is
510  marked by a NULL string value). For example, MPI_COMM_WORLD may
511  not appear as a symbol in an MPI process, but the debugger needs to
512  be able to map this name to a valid handle. MPI implementations
513  not requiring this mapping can either have a NULL value for this
514  variable or have a single entry that has a NULL string value. This
515  variable is not valid until after a successfull call to
516  mpidbg_init_per_process(). */
517 extern struct mpidbg_name_map_t *mpidbg_comm_name_map;
518 
519 /* Global variable *in the DLL* describing the DLL's capabilties with
520  regards to error handlers. This value is valid after a successfull
521  call to mpidbg_init_per_process(). */
522 extern enum mpidbg_errhandler_capabilities_t mpidbg_errhandler_capabilities;
523 
524 /* Global variable *in the DLL* that is an array of MPI error handler
525  handle names -> handle mappings. It is analogous to
526  mpidbg_comm_name_map; see above for details. */
527 extern struct mpidbg_name_map_t *mpidbg_errhandler_name_map;
528 
529 /**************************************************************************
530  * Functions
531  **************************************************************************/
532 
533 /*-----------------------------------------------------------------------
534  * DLL infrastructure functions
535  *-----------------------------------------------------------------------*/
536 
537 /* This function must be called once before any other mpidbg_*()
538  function is called, and before most other global mpidbg_* data is
539  read. It is only necessary to call this function once for a given
540  debugger instantiation. This function will initialize all mpidbg
541  global state, to include setting all relevant global capability
542  flags.
543 
544  Parameters:
545 
546  IN: callbacks: Table of pointers to the debugger functions. The DLL
547  need only save the pointer, the debugger promises to
548  maintain the table of functions valid for as long as
549  needed. The table remains the property of the
550  debugger, and should not be altered or deallocated
551  by the DLL. This applies to all of the callback
552  tables.
553 
554  This function will return:
555 
556  MPIDBG_SUCCESS: if all initialization went well
557  MPIDBG_ERR_*: if something went wrong.
558 */
559 int mpidbg_init_once(const mqs_basic_callbacks *callbacks);
560 
561 /*-----------------------------------------------------------------------*/
562 
563 /* Query the DLL to find out what version of the interface it
564  supports.
565 
566  Parameters:
567 
568  None.
569 
570  This function will return:
571 
572  MPIDBG_INTERFACE_VERSION
573 */
574 
575 int mpidbg_interface_version_compatibility(void);
576 
577 /*-----------------------------------------------------------------------*/
578 
579 /* Returns a string describing this DLL.
580 
581  Parameters:
582 
583  None
584 
585  This function will return:
586 
587  A null-terminated string describing this DLL.
588 */
589 char *mpidbg_version_string(void);
590 
591 /*-----------------------------------------------------------------------*/
592 
593 /* Returns the address width that this DLL was compiled with.
594 
595  Parameters:
596 
597  None
598 
599  This function will return:
600 
601  sizeof(mqs_taddr_t)
602 */
603 
604 int mpidbg_dll_taddr_width(void);
605 
606 /*-----------------------------------------------------------------------*/
607 
608 /* Setup debug information for a specific image, this must save the
609  callbacks (probably in the mqs_image_info), and use those functions
610  for accessing this image.
611 
612  The DLL should use the mqs_put_image_info and mqs_get_image_info
613  functions to associate whatever information it wants to keep with
614  the image (e.g., all of the type offsets it needs could be kept
615  here). The debugger will call mqs_destroy_image_info when it no
616  longer wants to keep information about the given executable.
617 
618  This will be called once for each executable image in the parallel
619  job.
620 
621  Parameters:
622 
623  IN: image: the application image.
624  IN: callbacks: Table of pointers to the debugger image-specific
625  functions. The DLL need only save the pointer, the
626  debugger promises to maintain the table of functions
627  valid for as long as needed. The table remains the
628  property of the debugger, and should not be altered
629  or deallocated by the DLL. This applies to all of
630  the callback tables.
631  IN/OUT: handle_types: a pointer to a pre-allocated struct
632  containing mqs_types for each of the MPI
633  handle types. Must be filled in with results
634  from mqs_find_type for each MPI handle type.
635 
636  This function will return:
637 
638  MPIDBG_SUCCESS: if all initialization went well
639  MPIDBG_ERR_NOT_SUPPORTED: if the image does not support the MPIDBG
640  interface. In this case, no other mpidbg functions
641  will be invoked on this image (not even
642  mpidbg_finalize_per_image()).
643  MPIDBG_ERR_*: if something went wrong.
644 */
645 int mpidbg_init_per_image(mqs_image *image,
646  const mqs_image_callbacks *callbacks,
647  struct mpidbg_handle_info_t *handle_types);
648 
649 /* This function will be called once when an application image that
650  previously had mpidbg_init_per_image() successfully invoked that is
651  now ending (e.g., the debugger is exiting, the debugger has
652  unloaded this image, etc.). This function can be used to clean up
653  any image-specific data.
654 
655  Parameters:
656 
657  IN: image: the application image.
658  IN: image_info: the info associated with the application image.
659 */
660 void mpidbg_finalize_per_image(mqs_image *image, mqs_image_info *image_info);
661 
662 /*-----------------------------------------------------------------------*/
663 
664 /* This function will only be called if mpidbg_init_per_image()
665  returned successfully, indicating that the image contains
666  information for MPI handle information. If you cannot tell whether
667  a process will have MPI handle information in it by examining the
668  image, you should return SUCCESS from mpidbg_init_per_image() and
669  use this function to check whether MPI handle information is
670  available in the process.
671 
672  Set up whatever process specific information we need. For instance,
673  addresses of global variables should be handled here rather than in
674  the image information, because if data may be in dynamic libraries
675  which could end up mapped differently in different processes.
676 
677  Note that certain global variables are not valid until after this
678  call completes successfully (see above; e.g.,
679  mpidbg_comm_capabilities, mpidbg_comm_name_mapping, etc.).
680 
681  Parameters:
682 
683  IN: process: the process
684  IN: callbacks: Table of pointers to the debugger process-specific
685  functions. The DLL need only save the pointer, the
686  debugger promises to maintain the table of functions
687  valid for as long as needed. The table remains the
688  property of the debugger, and should not be altered
689  or deallocated by the DLL. This applies to all of
690  the callback tables.
691  IN/OUT: handle_types: the same handle_types that was passed to
692  mqs_init_per_image. It can be left unaltered
693  if the results from mqs_init_per_image were
694  sufficient, or modified if necessary to be
695  specific to this process.
696 
697  This function will return:
698 
699  MPIDBG_SUCCESS: if all initialization went well
700  MPIDBG_ERR_NOT_SUPPORTED: if the process does not support the MPIDBG
701  interface. In this case, no other mpidbg functions
702  will be invoked on this image (not even
703  mpidbg_finalize_per_process()).
704  MPIDBG_ERR_*: if something went wrong.
705 */
706 int mpidbg_init_per_process(mqs_process *process,
707  const mqs_process_callbacks *callbacks,
708  struct mpidbg_handle_info_t *handle_types);
709 
710 /* This function will be called once when an application image that
711  previously had mpidbg_init_per_process() successfully invoked that
712  is now ending (e.g., the debugger is exiting, the debugger has
713  stopped executing this process, etc.). This function can be used
714  to clean up any process-specific data.
715 
716  Parameters:
717 
718  IN: process: the application process.
719  IN: process_info: the info associated with the application process.
720 */
721 void mpidbg_finalize_per_process(mqs_process *process,
722  mqs_process_info *process_info);
723 
724 /*-----------------------------------------------------------------------
725  * MPI handle query functions
726  * MPI_Comm
727  *-----------------------------------------------------------------------*/
728 
729 /* Query a specific MPI_Comm handle and, if found and valid, allocate
730  a new instance of the mpidbg_comm_info_t struct and all of its
731  internal data, and fill it in with information about the underlying
732  corresponding MPI communicator object.
733 
734  Parameters:
735 
736  IN: image: image
737  IN: image_info: image info that was previously "put"
738  IN: process: process
739  IN: process_info: process info that was previously "put"
740  IN: comm: communicator handle
741  OUT: info: pointer to be filled with a newly-allocated struct
742  mpidbg_comm_info_t
743 
744  This function will return:
745 
746  MPIDBG_SUCCESS: if the handle is valid, was found, and the info
747  parameter was filled in successfully.
748  MPIDBG_ERR_NOT_FOUND: if the handle is not valid / found.
749  MPIDBG_ERR_UNSUPPORTED: if this function is unsupported.
750 */
751 int mpidbg_comm_query(mqs_image *image, mqs_image_info *image_info,
752  mqs_process *process, mqs_process_info *process_info,
753  mqs_taddr_t c_comm, struct mpidbg_comm_info_t **info);
754 
755 /* Query function to turn a Fortran INTEGER handle into its equivalent
756  C handle (that can then be queried with mpidbg_comm_query()).
757  mqs_taddr_t is used in order to guarantee to be large enough to
758  hold a Fortran INTEGER.
759 
760  Parameters:
761 
762  IN: image: image
763  IN: image_info: image info that was previously "put"
764  IN: process: process
765  IN: process_info: process info that was previously "put"
766  IN: f77_comm: a zero-padded Fortran integer containing the Fortran
767  handle of the communicator.
768  OUT: c_comm: a C handle suitable to pass to mpidbg_comm_query().
769 
770  This function returns:
771 
772  MPIDBG_SUCCESS: if the handle is valid, was found, and the c_comm
773  parameter was filled in successfully.
774  MPIDBG_ERR_NOT_FOUND: if the handle is not valid / found.
775  MPIDBG_ERR_UNSUPPORTED: if this function is unsupported.
776 */
777 int mpidbg_comm_f2c(mqs_image *image, mqs_image_info *image_info,
778  mqs_process *process, mqs_process_info *process_info,
779  mqs_taddr_t f77_comm, mqs_taddr_t *c_comm);
780 
781 /* Query function to turn a C++ handle into its equivalent C handle
782  (that can then be queried with mpidbg_comm_query()). Pass the
783  pointer to the object as the cxx_comm (because we can't pass the
784  object itself); we return the C handle.
785 
786  --> JMS Need more discussion here -- George has some opinion. He
787  thinks we don't need this.
788  Parameters:
789 
790  IN: image: image
791  IN: image_info: image info that was previously "put"
792  IN: process: process
793  IN: process_info: process info that was previously "put"
794  IN: cxx_comm: a pointer to the MPI handle object
795  IN: comm_type: one of 0, MPIDBG_COMM_INFO_CARTESION,
796  MPIDBG_COMM_INFO_GRAPH, or
797  MPIDBG_COMM_INFO_INTERCOMM indicating whether the
798  object is an MPI::Comm, MPI::Cartcomm,
799  MPI::Graphcomm, or MPI::Intercomm.
800  OUT: c_comm: a C handle suitable to pass to mpidbg_comm_query().
801 
802  This function returns:
803 
804  MPIDBG_SUCCESS: if the handle is valid, was found, and the c_comm
805  parameter was filled in successfully.
806  MPIDBG_ERR_NOT_FOUND: if the handle is not valid / found.
807  MPIDBG_ERR_UNSUPPORTED: if this function is unsupported.
808 */
809 int mpidbg_comm_cxx2c(mqs_image *image, mqs_image_info *image_info,
810  mqs_process *process, mqs_process_info *process_info,
811  mqs_taddr_t cxx_comm,
812  enum mpidbg_comm_info_bitmap_t comm_type,
813  mqs_taddr_t *c_comm);
814 
815 /*-----------------------------------------------------------------------
816  * MPI handle query functions
817  * MPI_Errhandler
818  *-----------------------------------------------------------------------*/
819 
820 /* These functions are analogous to the mpidbg_comm_* functions, but
821  for MPI_Errhandler. Note that there is no need for a
822  "errhandler_type" argument to the cxx2c function because
823  MPI::Errhandler has no derived classes. */
824 
825 int mpidbg_errhandler_query(mqs_image *image, mqs_image_info *image_info,
826  mqs_process *process, mqs_process_info *process_info,
827  mqs_taddr_t errhandler,
828  struct mpidbg_errhandler_info_t **info);
829 int mpidbg_errhandler_f2c(mqs_image *image, mqs_image_info *image_info,
830  mqs_process *process, mqs_process_info *process_info,
831  mqs_taddr_t f77_errhandler,
832  mqs_taddr_t *c_errhandler);
833 int mpidbg_errhandler_cxx2c(mqs_image *image, mqs_image_info *image_info,
834  mqs_process *process, mqs_process_info *process_info,
835  mqs_taddr_t cxx_errhandler,
836  mqs_taddr_t *c_errhandler);
837 
838 /*-----------------------------------------------------------------------
839  * MPI handle query functions
840  * MPI_Request
841  *-----------------------------------------------------------------------*/
842 
843 /* These functions are analogous to the mpidbg_comm_* functions, but
844  for MPI_Request. */
845 
846 int mpidbg_request_query(mqs_image *image, mqs_image_info *image_info,
847  mqs_process *process, mqs_process_info *process_info,
848  mqs_taddr_t request,
849  struct mpidbg_request_info_t **info);
850 int mpidbg_request_f2c(mqs_image *image, mqs_image_info *image_info,
851  mqs_process *process, mqs_process_info *process_info,
852  mqs_taddr_t f77_request, mqs_taddr_t *c_request);
853 int mpidbg_request_cxx2c(mqs_image *image, mqs_image_info *image_info,
854  mqs_process *process, mqs_process_info *process_info,
855  mqs_taddr_t cxx_request,
856  enum mpidbg_request_info_bitmap_t request_type,
857  mqs_taddr_t *c_request);
858 
859 /*-----------------------------------------------------------------------
860  * MPI handle query functions
861  * MPI_Status
862  *-----------------------------------------------------------------------*/
863 
864 /* These functions are analogous to the mpidbg_comm_* functions, but
865  for MPI_Status. */
866 
867 int mpidbg_status_query(mqs_image *image, mqs_image_info *image_info,
868  mqs_process *process, mqs_process_info *process_info,
869  mqs_taddr_t status,
870  struct mpidbg_status_info_t **info);
871 int mpidbg_status_f2c(mqs_image *image, mqs_image_info *image_info,
872  mqs_process *process, mqs_process_info *process_info,
873  mqs_taddr_t f77_status, mqs_taddr_t *c_status);
874 int mpidbg_status_cxx2c(mqs_image *image, mqs_image_info *image_info,
875  mqs_process *process, mqs_process_info *process_info,
876  mqs_taddr_t cxx_status,
877  mqs_taddr_t *c_status);
878 
879 #endif /* __MPIDBG_INTERFACE_H__ */
Definition: mpihandles_interface.h:179
Definition: msgq_interface.h:516
Definition: mpihandles_interface.h:57
Definition: mpihandles_interface.h:249
Definition: mpihandles_interface.h:436
Definition: msgq_interface.h:506
Definition: mpihandles_interface.h:353
Definition: msgq_interface.h:484
Definition: mpihandles_interface.h:383
Definition: mpihandles_interface.h:147
Definition: mpihandles_interface.h:166
Definition: evdns.c:158