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