Function Name Prefix Convention
This page describes the convention for function names in MPICH. The prefixes to function names indicate at which level the function is implemented, and by which level it is intended to be used.
I believe that this is how the prefixes were intended to be used:
An interface (e.g., MPI, ADI3, channel) is identified by a prefix (e.g., MPI, MPID, MPIDI_CH3). For a particular interface with prefix XXX, functions with the XXX_ prefix and XXXU_ prefix are part of the API, with the XXX_ functions being implemented by the lower layer and called by the upper layer, and the XXXU_ functions being implemented by the upper layer to be called by the lower layer (U may stand for "upcall"). Functions with the XXXI_ prefix are not part of the API and are implemented by the lower layer to be used internally by the lower layer, and so should not be called directly by the upper layer. E.g. For the ADI3 interface, MPID_ functions are implemented by CH3 and are called by the MPI layer. MPIDU_ functions are implemented by the MPI layer and are called by CH3. CH3 has internal functions which have the MPIDI_ prefix. Note that channels are part of the CH3 implementation, and so all channel functions should have MPIDI_ prefixes (specifically MPIDI_CH3_, MPIDI_CH3I_, etc.).
Repeating for emphasis: XXXU_ functions being implemented by the upper layer to be called by the lower layer (U may stand for "upcall")
A little more specifically:
- MPI_ functions are implemented by the MPI level to be used by the application
- MPIU_ functions are implemented by the MPI level in src/util/ to be used by the MPI level and below
- MPIR_ MPI functionality to be used by the MPI level and below (technically a synonym for MPIU_?)
- MPIRI_ functions implemented in the MPI layer for use within it (does not exist today)
- MPIC_ MPI Collective helper functions to be used by the MPI level only (special case of MPIRI_?)
- MPID_ functions are implemented by the device to be used by the MPI level in src/mpid/<device>
- MPIDU_ device independent functionality (only?) in src/mpid/common or src/mpid/include to be optionally used by the device level and below, but not above.
- MPIDI_ functions are implemented at the device level (in src/mpid/<device>) to be used in the specific device implementing it and below, (not above).
- MPL_ MPICH Portability Library - can be used anywhere inside MPICH
- OPA_ Open Portable Atomics - can be used anywhere inside MPICH
- In the CH3 device:
- MPIDI_CH3_ functions are implemented by the channel in src/mpid/ch3/<channel> used by CH3
- MPIDI_CH3U_ functions are implemented by the CH3 used by the channel (and probably CH3?) but not above
- MPIDI_CH3I_ functions are implemented by the channel used by the channel but not above.
- In the CH4 device:
- MPIDI_CH4 functions implemented by CH4 to be used at the device level
- MPIDI_CH4U_ optional transport independent functionality (e.g. MPICH active message fallback)
- MPIDI_CH4I_ functions implemented by CH4 to be used by CH4 but not above
MPICH 3.3 Greenfield Refactor
- MPID - The ADI interface. Used by the upper level (the MPI routines) to invoke the device.
- MPIR - Service routines and structures (only) in the upper (MPI) level. Should replace the “MPIC” names. Make MPIR only visible within upper layer. Should never be called/referred to within the MPID layer.
- MPL - Utility routines. Replaces any remaining MPIU routines
- MPIU - Upcall routines and structures. Used by the ADI to invoke routines in the upper level. New meaning; essentially the counterpart of MPID.
- MPIDU - Device utility routines. These are intended to support device implementation needs (such as processing MPI datatypes or providing access to node shared memory) independent of any specific device. Should never be called from the upper layer.
Changes to be made to existing code
- Convert internal MPI layer functionality to MPII?
- Eliminate MPIR/MPIC
- Move all independent utilities in src/util to MPL
- MPL_Malloc, MPL_Free
- thread safety routines
- MPIU timer code
- et al.
- Reuse MPIU prefix for upcalls from the device
- Export all src/mpid/common code as MPIDU
- Devices can #define MPID_<foo> MPIDU_<foo> when the common code impl is good enough
- e.g. Segment routines