UniMCI User Documentation |
![]() |
---|
UniMCI provides a configuration tool, named "unimci-config", in the "bin" directory of its installation. The tool can be used to retrieve the libraries, library directories, flags, and compilers, that are needed to compile and link with UniMCI and its MPI checker. This data should be queried while configuring a tool or application that wants to use UniMCI.
Below is the list of all options provided by the configuration tool:
Usage: unimci-config [--help] [--version] [--checker-version] [--checker-name] [--ldflags] [--cc] [--cflags] [--clibs] [--clib-dirs] [--cxx] [--cxxflags] [--cxxlibs] [--cxxlib-dirs] [--f77] [--f77flags] [--f77libs] [--f77lib-dirs] [--f90] [--f90flags] [--f90libs] [--f90lib-dirs]
UniMCI provides several functions to retrieve MPI checking results as well as check calls for each MPI function. To use UniMCI it is necessary to include its main header file "unimci.h". This file includes four different headers that contain the message record that holds checking results ("unimci-message.h"), core functions to control UniMCI and to retrieve messages ("unimci-core.h"), and two header files for all MPI-1 and MPI-2 calls ("unimci-mpi-1.h", "unimci-mpi-2.h"). The MPI-2 calls are only added if you specify the macro UNIMCI_MPI2 (e.g. gcc -DUNIMCI_MPI2 my_unimci_test.c). Make sure to only specify this macro if your MPI implementation has full MPI-2 support, UniMCI does not supports MPI-2 for MPI implementations with partial MPI-2 support (e.g. lam MPI).
The UniMCI message record (UNIMCI_MSG) offers a representation of data returned by an MPI checker. Three different types of messages exist: Infos, Warnings, and Errors. The type of the message is stored in the record (UNIMCI_MSG::msgType). Further, the record contains a text that describes the MPI call that is associated with the message (UNIMCI_MSG::strCallInfo), the actual message text (UNIMCI_MSG::strText), and it may also contain a HTML link to a passage of the MPI standard that refers to this message. In addition a message may refer to more than one process, i.e., it is a global message. These messages contain information about all the processes involved in the message (UNIMCI_MSG::isGlobal, UNIMCI_MSG::numParticipatingRanks, UNIMCI_MSG::participatingRanks).
To issue the MPI checking, two check functions are used to perform checks before and after the actual call is issued. Thus, a regular MPI or PMPI call like:
MPI_X(<params>);
Has to be modified to:
UNIMCI_check_pre__MPI_X(<params>, <SourceFileName>, <SourceLine>, <ID>); MPI_X(<params>); UNIMCI_check_post__MPI_X(<params>, <SourceFileName>, <SourceLine>, <ID>);
The additional arguments <SourceFileName> and <SourceLine> are used to identify the source code that issues the MPI call. If this information is not available you should use <SourceFileName>="" and <SourceLine>=0 to identify an unknown location. The extra argument <ID> may be used to identify an individual MPI call. If a check with a given ID leads to the generation of a UniMCI message, this ID will be returned in the message. This is used for MPI checkers that perform checks in an asynchronous manner, thus, they may return messages not directly after a check-pre or check-post call.
The underlying MPI checker usually needs to know the MPI bindings that are currently used (C or Fortran), which is set with UNIMCI_set_binding_language. The default setting assumes that the C bindings are used, so if you are using the Fortran bindings of MPI, you should set the binding language to Fortran.
Messages generated by the MPI checker are retrieved with the UniMCI functions UNIMCI_has_msg and UNIMCI_pop_msg. The first function is used to determine whether a message is available, and the second function is used to retrieve a message. In order to guarantee the retrieval of all messages, the UniMCI user has to check for messages after each check-pre and each check-post call. Otherwise messages may be lost, due to an application crash related to wrong MPI usage. Retrieved messages have to be freed with UNIMCI_msg_free. The UniMCI user may incorporate this information into his own or an extra output, as well as discard this information.
You can also get all messages in an array by using UNIMCI_get_msgs and querry the total number of outstanding messages UNIMCI_get_num_msgs.
In addition, some MPI checkers may perform an asynchronous MPI checking for performance reasons. In such a situation an MPI error may not be detected directly after a check-pre or check-post call, but at a later time. To guarantee the retrieval of these messages the UniMCI user may specify a call-back function. This function is set with UNIMCI_register_msg_callback. The call-back function, if specified, is invoked for these asynchronously detected MPI errors. Note that this may be done by an additional thread created by the MPI checker, thus, you should guarantee mutual exclusion for data touched by the call-back. Further, even when specifing a call-back function it is still necessary to perform a regular message query after each check-pre and each check-post function.
If UniMCI is used by an MPI wrapping tool, it may be convenient to hide MPI usage of the tool itself. This is achieved by using the functions UNIMCI_on and UNIMCI_off. Note that you have to take special care with this feature, as switching off UniMCI only for some functions may lead to the detection of false positives. This happens if the MPI checker is not informed about some MPI calls that relate to each other, e.g., is only informed about an MPI_Wait but not about the preceding MPI_Isend.
Example - See an UniMCI usage example
Overview - Back to the main page