Difference between revisions of "Function Name Prefix Convention"

From Mpich
Jump to: navigation, search
(Interface Layering)
 
(40 intermediate revisions by the same user not shown)
Line 11: Line 11:
 
* '''MPI_''' functions are implemented by the MPI level to be used by the application
 
* '''MPI_''' functions are implemented by the MPI level to be used by the application
 
* '''MPIU_''' functions are implemented by the MPI level in <tt>src/util/</tt> to be used by the MPI level and below
 
* '''MPIU_''' functions are implemented by the MPI level in <tt>src/util/</tt> 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_?)
+
* '''MPIR_''' MPI functionality to be used by the MPI level and below (<span style="color:#ff0000">technically a synonym for MPIU_?</span>)
* '''MPIC_''' MPI Collective helper functions to be used by the MPI level only (could be more accurately MPIRI_?)
+
* '''MPIC_''' MPI Collective helper functions to be used by the MPI level only
 
* '''MPID_''' functions are implemented by the device to be used by the MPI level in <tt>src/mpid/''<device>''</tt>
 
* '''MPID_''' functions are implemented by the device to be used by the MPI level in <tt>src/mpid/''<device>''</tt>
 
* '''MPIDU_''' device independent functionality (''only?'') in <tt>src/mpid/common</tt> or <tt>src/mpid/include</tt> to be ''optionally'' used by the device level and below, but not above.
 
* '''MPIDU_''' device independent functionality (''only?'') in <tt>src/mpid/common</tt> or <tt>src/mpid/include</tt> to be ''optionally'' used by the device level and below, but not above.
 
* '''MPIDI_''' functions are implemented at the device level (in <tt>src/mpid/''<device>''</tt>) to be used in the specific device implementing it and below, (not above).
 
* '''MPIDI_''' functions are implemented at the device level (in <tt>src/mpid/''<device>''</tt>) 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:
 
* In the CH3 device:
 
** '''MPIDI_CH3_''' functions are implemented by the channel in <tt>src/mpid/ch3/''<channel>''</tt> used by CH3
 
** '''MPIDI_CH3_''' functions are implemented by the channel in <tt>src/mpid/ch3/''<channel>''</tt> used by CH3
Line 23: Line 25:
 
** '''MPIDI_CH4''' functions implemented by CH4 to be used at the device level
 
** '''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_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
  
== Reality ==
 
  
So that was what was ''supposed'' to be the naming convention, but when one looks at the code, it doesn't match up:
+
== MPICH 3.3 Greenfield Refactor ==
* MPIDI_FUNC_ENTER is defined in src/include/mpiimpl.h: This should be MPIU_FUNC_ENTER
+
NOTE: Prefixes involving CH4 will use lowercase after the prefix. (e.g. MPIDI_CH4R_send)
* MPIDI_Sock_update_sock_set and many other MPIDI_ macros are defined in src/mpid/common: These should have the MPIDU_ prefix
+
=== Interface Layering ===
* There are also MPIDU_CH3I_ and MPIDU_CH3U_ prefixes which don't match any of the rules
+
*'''MPI layer:'''
* Oh, and just forget about prefix conventions in Nemesis :-)
+
** Up interface: MPI, MPIX
 +
** Down interface: MPIR
 +
** Horizontal interface: MPII
  
Considering there are many places where this isn't followed, and that changing function names or moving functions could really mess up external collaborators who are trying to track our code, what do we want to do?
+
*'''Device layer:'''
* Nothing, just follow the correct convention from here on
+
** Up interface: MPID
* Change it all and hope collaborators can keep up
+
** Down interface: MPIDIR
* Fix particularly bad cases, and leave the rest
+
** Horizontal interface: MPIDI
* Relax the prefix rules to closer match reality
+
** Generic functionality: MPIDIG
 +
*'''Device independent (generic) functionality'''
 +
** Up interface: N/A
 +
** Down interface: N/A
 +
** Horizontal interface: MPIDGI
 +
** Generic functionality: MPIDG
  
= Naming in CH4 =
+
*'''Netmod layer:'''
With the relatively clean slate in CH4, now is the time to make intrusive changes we otherwise held off on to not upset downstream partners.
+
** Up interface: MPIDI_NM
 +
** Horizontal interface: MPIDI_OFI, MPIDI_UCX, ...
 +
** Generic functionality: MPIDI_NMG
 +
 
 +
*'''Shmmod layer:'''
 +
** Up interface: MPIDI_SHM
 +
** Horizontal interface: MPIDI_CMA, MPIDI_POSIX, ...
 +
** Generic functionality: MPIDI_SHMG
 +
 
 +
[[File:MPICH-CH4-Interfaces.png]]
 +
 
 +
=== Changes to be made to existing code ===
 +
 
 +
* Move independent utilities in <tt>src/util</tt> to MPL
 +
** <strike>Locking primitives</strike>
 +
** <strike><tt>MPL_Malloc, MPL_Free</tt></strike>
 +
** <strike>Timers</strike>
 +
** and others...
 +
* <strike>Integrate MPL into ROMIO</strike>
 +
* Export device fallback code as MPIDU
 +
** <strike><tt>src/mpid/common/sched</tt></strike>
 +
** <tt>src/mpid/common/datatype</tt>
 +
** default collective algorithms
 +
** and others...
  
 
[[Category:Design_Documents]]
 
[[Category:Design_Documents]]

Latest revision as of 21:06, 4 May 2016

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_?)
  • MPIC_ MPI Collective helper functions to be used by the MPI level only
  • 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

NOTE: Prefixes involving CH4 will use lowercase after the prefix. (e.g. MPIDI_CH4R_send)

Interface Layering

  • MPI layer:
    • Up interface: MPI, MPIX
    • Down interface: MPIR
    • Horizontal interface: MPII
  • Device layer:
    • Up interface: MPID
    • Down interface: MPIDIR
    • Horizontal interface: MPIDI
    • Generic functionality: MPIDIG
  • Device independent (generic) functionality
    • Up interface: N/A
    • Down interface: N/A
    • Horizontal interface: MPIDGI
    • Generic functionality: MPIDG
  • Netmod layer:
    • Up interface: MPIDI_NM
    • Horizontal interface: MPIDI_OFI, MPIDI_UCX, ...
    • Generic functionality: MPIDI_NMG
  • Shmmod layer:
    • Up interface: MPIDI_SHM
    • Horizontal interface: MPIDI_CMA, MPIDI_POSIX, ...
    • Generic functionality: MPIDI_SHMG

MPICH-CH4-Interfaces.png

Changes to be made to existing code

  • Move independent utilities in src/util to MPL
    • Locking primitives
    • MPL_Malloc, MPL_Free
    • Timers
    • and others...
  • Integrate MPL into ROMIO
  • Export device fallback code as MPIDU
    • src/mpid/common/sched
    • src/mpid/common/datatype
    • default collective algorithms
    • and others...