OpenMPI 0.1.1

- Main Page
- Related Pages
- Modules
- Data Structures
- Files

- File List
- Globals

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 */
57 struct mpidbg_handle_info_t {
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 */
147 struct mpidbg_process_t {
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). */
166 struct mpidbg_name_map_t {
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. */
179 struct mpidbg_attribute_pair_t {
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
249 struct mpidbg_comm_info_t {
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
353 struct mpidbg_request_info_t {
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
383 struct mpidbg_status_info_t {
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
436 struct mpidbg_errhandler_info_t {
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__ */
mpidbg_attribute_pair_t
Definition: mpihandles_interface.h:179
mqs_process_callbacks
Definition: msgq_interface.h:516
mpidbg_handle_info_t
Definition: mpihandles_interface.h:57
mpidbg_comm_info_t
Definition: mpihandles_interface.h:249
mpidbg_errhandler_info_t
Definition: mpihandles_interface.h:436
mqs_image_callbacks
Definition: msgq_interface.h:506
mpidbg_request_info_t
Definition: mpihandles_interface.h:353
mqs_basic_callbacks
Definition: msgq_interface.h:484
mpidbg_status_info_t
Definition: mpihandles_interface.h:383
mpidbg_process_t
Definition: mpihandles_interface.h:147
mpidbg_name_map_t
Definition: mpihandles_interface.h:166
request
Definition: evdns.c:158