Changeset 5708

Show
Ignore:
Timestamp:
11/05/09 12:55:33 (3 weeks ago)
Author:
balaji
Message:

Doxygen powered documentation for Hydra's internal interfaces. Fixes
ticket #910.

Location:
mpich2/trunk/src/pm/hydra
Files:
1 added
8 modified

Legend:

Unmodified
Added
Removed

  • mpich2/trunk/src/pm/hydra/Makefile.am

    r5584 r5708  
    4343# A special alternate installation target when using multiple process managers 
    4444install-alt: install-alt-ui install-alt-pm 
     45 
     46htmldoc: 
     47        if test "@DOXYGEN@" != "" ; then @DOXYGEN@ hydra-doxygen.cfg ; fi 

  • mpich2/trunk/src/pm/hydra/configure.in

    r5681 r5708  
    4141   HYDRA_VERSION=$MPICH2_VERSION 
    4242fi 
     43AC_SUBST(HYDRA_VERSION) 
    4344AC_DEFINE_UNQUOTED(HYDRA_VERSION,"$HYDRA_VERSION",[Hydra version information]) 
    4445AC_DEFINE_UNQUOTED(HYDRA_CC,"$CC",[C compiler]) 
    … …  
    4748AC_DEFINE_UNQUOTED(HYDRA_F90,"$F90",[Fortran 90 compiler]) 
    4849AC_DEFINE_UNQUOTED(HYDRA_CONFIGURE_ARGS_CLEAN,"$ac_configure_args",[Configure arguments]) 
     50 
     51# Documentation 
     52AC_PATH_PROG([DOXYGEN],[doxygen],,$PATH) 
     53AC_SUBST(DOXYGEN) 
     54AC_SUBST(top_srcdir) 
    4955 
    5056# Find the full path of the source dir (for VPATH builds) 
    … …  
    498504        css/src/cssi_init.c 
    499505        css/include/cssi.h 
     506        hydra-doxygen.cfg 
    500507) 

  • mpich2/trunk/src/pm/hydra/pm/include/pmci.h

    r5472 r5708  
    88#define PMCI_H_INCLUDED 
    99 
     10/** @file pmci.h */ 
     11 
     12/*! \addtogroup pmci Process Management Control Interface 
     13 * @{ 
     14 */ 
     15 
     16/** 
     17 * \brief HYD_pmci_launch_procs - Launch processes 
     18 * 
     19 * This function appends the appropriate process management interface 
     20 * specific environment and other functionality 
     21 */ 
    1022HYD_status HYD_pmci_launch_procs(void); 
     23 
     24/** 
     25 * \brief HYD_pmci_wait_for_completion - Wait for launched processes to complete 
     26 * 
     27 * Wait for launched processes to complete 
     28 */ 
    1129HYD_status HYD_pmci_wait_for_completion(void); 
     30 
     31/** 
     32 * \brief HYD_pmci_finalize - Finalize process management control device 
     33 * 
     34 * This function cleans up any relevant state that the process 
     35 * management control device maintained. 
     36 */ 
    1237HYD_status HYD_pmci_finalize(void); 
    1338 
     39/*! 
     40 * @} 
     41 */ 
     42 
    1443#endif /* PMCI_H_INCLUDED */ 

  • mpich2/trunk/src/pm/hydra/rmk/include/rmki.h.in

    r5486 r5708  
    88#define RMKI_H_INCLUDED 
    99 
     10/** @file rmki.h.in */ 
     11 
    1012#include "hydra.h" 
    1113 
     14/*! \addtogroup rmki Resource Management Kernel Interface 
     15 * @{ 
     16 */ 
     17 
     18/** 
     19 * \brief Function pointers for device specific implementations of 
     20 * different RMK functions 
     21 */ 
    1222struct HYD_rmki_fns { 
     23    /** \brief Query node list information */ 
    1324    HYD_status(*query_node_list) (int *num_cores, struct HYD_proxy **proxy_list); 
    1425}; 
    1526 
     27/** \cond */ 
    1628extern struct HYD_rmki_fns HYD_rmki_fns; 
     29/** \endcond */ 
    1730 
     31/** 
     32 * \brief HYD_rmki_init - Initialize the resource management kernel 
     33 * 
     34 * \param[in]   rmk     Resource management kernel to use 
     35 * 
     36 * Initializes the resource management kernel 
     37 */ 
    1838HYD_status HYD_rmki_init(char *rmk); 
    1939 
    20 /* Non-zero nodes means that the RMK should allocate the nodes if needed */ 
     40/** 
     41 * \brief HYD_rmki_query_node_list - Query node list information 
     42 * 
     43 * \param[in,out]   num_cores   Number of cores available (non-zero cores means 
     44 *                              that the RMK should allocate the nodes if needed 
     45 * \param[out]      proxy_list  List of proxy structures containing the list of hosts 
     46 */ 
    2147HYD_status HYD_rmki_query_node_list(int *num_cores, struct HYD_proxy **proxy_list); 
     48 
     49/*! 
     50 * @} 
     51 */ 
    2252 
    2353/* Each resource management kernel has to expose an initialization function */ 

  • mpich2/trunk/src/pm/hydra/tools/bind/bind.h

    r5698 r5708  
    88#define BIND_H_INCLUDED 
    99 
     10/** @file bind.h */ 
     11 
    1012#include "hydra_utils.h" 
     13 
     14/*! \cond */ 
    1115 
    1216#define HYDT_TOPO_CHILD_ID(obj) \ 
    1317    ((((char *) obj) - ((char *) obj->parent->children)) / sizeof(struct HYDT_topo_obj)) 
    1418 
     19/*! \endcond */ 
     20 
     21/*! \addtogroup bind Process Binding Interface 
     22 * @{ 
     23 */ 
     24 
     25/** 
     26 * \brief HYDT_bind_support_level_t 
     27 * 
     28 * Level of binding support offered by the binding library. 
     29 */ 
    1530typedef enum { 
     31    /** \brief No support is provided */ 
    1632    HYDT_BIND_NONE = 0, 
     33 
     34    /** \brief Provides information on number of processing elements 
     35     * in the system, and allows for process binding */ 
    1736    HYDT_BIND_BASIC, 
     37 
     38    /** \brief Provides information about the topology of the 
     39     * processing elements (nodes, processors, cores, threads). */ 
    1840    HYDT_BIND_TOPO, 
     41 
     42    /** \brief Provides information about the topology of the 
     43     * processing elements (nodes, processors, cores, threads) as well 
     44     * as the memory hierarchy (caches, memory). */ 
    1945    HYDT_BIND_MEMTOPO 
    2046} HYDT_bind_support_level_t; 
    2147 
     48 
     49/** 
     50 * \brief HYDT_topo_obj_type_t 
     51 * 
     52 * Type of object in the hardware topology map. 
     53 */ 
    2254typedef enum { 
    23     HYDT_TOPO_MACHINE = 0, /* Cache-coherent set of processors */ 
    24     HYDT_TOPO_NODE, /* Sockets sharing memory dimms */ 
     55    /** \brief Cache coherent set of processors */ 
     56    HYDT_TOPO_MACHINE = 0, 
     57 
     58    /** \brief Sockets sharing memory dimms */ 
     59    HYDT_TOPO_NODE, 
     60 
     61    /** \brief A physical socket, possibly comprising of many cores */ 
    2562    HYDT_TOPO_SOCKET, 
     63 
     64    /** \brief A core, possibly comprising of many hardware threads */ 
    2665    HYDT_TOPO_CORE, 
     66 
     67    /** \brief A hardware thread */ 
    2768    HYDT_TOPO_THREAD, 
    28     HYDT_TOPO_END /* The last element */ 
     69 
     70    /** \brief Marker for the last element in the enum */ 
     71    HYDT_TOPO_END 
    2972} HYDT_topo_obj_type_t; 
    3073 
     74 
     75/** 
     76 * \brief An object in the hardware topology map 
     77 * 
     78 * The overall topology is represented as a hierarchical structure of 
     79 * objects. A machine object contains several node objects (which are 
     80 * collections of sockets that share a memory region). Each node 
     81 * object contains several sockets. Each socket contains several 
     82 * cores. Each core contains several threads. 
     83 */ 
    3184struct HYDT_topo_obj { 
     85    /** \brief Object type */ 
    3286    HYDT_topo_obj_type_t type; 
    3387 
    34     int os_index; /* OS index */ 
     88    /** \brief OS index of this object type (-1 if this type has 
     89     * children) */ 
     90    int os_index; 
    3591 
     92    /** \brief Parent object of which this is a part */ 
    3693    struct HYDT_topo_obj *parent; 
    3794 
     95    /** \brief Number of children objects */ 
    3896    int num_children; 
     97 
     98    /** \brief Array of children objects */ 
    3999    struct HYDT_topo_obj *children; 
    40100 
    41     /* Depth of the shared memory regions. This is a pointer to 
    42      * accomodate multiple levels of memory shared by this set of 
     101    /** \brief Depth of the shared memory regions. This is a pointer 
     102     * to accomodate multiple levels of memory shared by this set of 
    43103     * processing units. */ 
    44104    int *shared_memory_depth; 
    45105}; 
    46106 
     107/** 
     108 * \brief Binding information for one machine in the system 
     109 * 
     110 * Contains private persistent information stored by the binding 
     111 * library. 
     112 */ 
    47113struct HYDT_bind_info { 
     114    /** \brief Support level provided by the binding library */ 
    48115    HYDT_bind_support_level_t support_level; 
    49116 
     117    /** \brief Binding library to use */ 
    50118    char *bindlib; 
     119 
     120    /** \brief Ordered OS index map to bind the processes */ 
    51121    int *bindmap; 
    52122 
    53     /* This is needed for all binding levels, except "NONE" */ 
     123    /** \brief Total processing units available on the machine. This 
     124     * is needed for all binding levels, except "NONE" */ 
    54125    int total_proc_units; 
    55126 
     127    /** \brief Top-level topology object */ 
    56128    struct HYDT_topo_obj machine; 
    57129}; 
    58130 
     131/*! \cond */ 
    59132extern struct HYDT_bind_info HYDT_bind_info; 
     133/*! \endcond */ 
    60134 
     135/** 
     136 * \brief HYDT_bind_init - Initialize the binding library 
     137 * 
     138 * \param[in]  binding   Binding pattern to use 
     139 * \param[in]  bindlib   Binding library to use 
     140 * 
     141 * This function initializes the binding library requested by the 
     142 * user. It also queries for the support provided by the library and 
     143 * stores it for future calls. 
     144 */ 
    61145HYD_status HYDT_bind_init(char *binding, char *bindlib); 
     146 
     147 
     148/** 
     149 * \brief HYDT_bind_finalize - Finalize the binding library 
     150 * 
     151 * This function cleans up any relevant state that the binding library 
     152 * maintained. 
     153 */ 
    62154void HYDT_bind_finalize(void); 
     155 
     156 
     157/** 
     158 * \brief HYDT_bind_process - Bind process to a processing element 
     159 * 
     160 * \param[in] os_index  The Operating System index to bind the process to 
     161 * 
     162 * This function binds a process to an appropriate OS index. If the OS 
     163 * index is negative, no binding needs to be performed. 
     164 */ 
    63165HYD_status HYDT_bind_process(int os_index); 
     166 
     167 
     168/** 
     169 * \brief HYDT_bind_get_os_index - Get the OS index for a process ID 
     170 * 
     171 * \param[in] process_id   The process index for which we need the OS index 
     172 * 
     173 * This function looks up the appropriate OS index (by wrapping around 
     174 * in cases where the process_id is larger than the number of 
     175 * available processing units). 
     176 */ 
    64177int HYDT_bind_get_os_index(int process_id); 
    65178 
     179/*! 
     180 * @} 
     181 */ 
     182 
    66183#endif /* BIND_H_INCLUDED */ 

  • mpich2/trunk/src/pm/hydra/tools/bootstrap/include/bsci.h.in

    r5486 r5708  
    88#define BSCI_H_INCLUDED 
    99 
     10/** @file bsci.h.in */ 
     11 
     12/*! \addtogroup bootstrap Bootstrap Control Interface 
     13 * @{ 
     14 */ 
     15 
     16/** 
     17 * \brief BSCI internal structure to maintain persistent information. 
     18 */ 
    1019struct HYDT_bsci_info { 
     20    /** \brief Boostrap executable to use */ 
    1121    char *bootstrap_exec; 
     22 
     23    /** \brief Enable/disable X-forwarding */ 
    1224    int  enablex; 
     25 
     26    /** \brief Enable/disable debugging */ 
    1327    int  debug; 
    1428}; 
    1529 
     30/** 
     31 * \brief Function pointers for device specific implementations of 
     32 * different BSCI functions. 
     33 */ 
    1634struct HYDT_bsci_fns { 
     35    /** \brief Launch processes */ 
    1736    HYD_status(*launch_procs) (char **global_args, const char *proxy_id_str, 
    1837                               struct HYD_proxy *proxy_list); 
     38 
     39    /** \brief Finalize the bootstrap control device */ 
    1940    HYD_status(*finalize) (void); 
     41 
     42    /** \brief Wait for bootstrap launched processes to complete */ 
    2043    HYD_status(*wait_for_completion) (struct HYD_proxy *proxy_list); 
     44 
     45    /** \brief Query for node list information */ 
    2146    HYD_status(*query_node_list) (int *num_cores, struct HYD_proxy **proxy_list); 
     47 
     48    /** \brief Query for the universe size */ 
    2249    HYD_status(*query_usize) (int *size); 
     50 
     51    /** \brief Query the ID of a proxy */ 
    2352    HYD_status(*query_proxy_id) (int *proxy_id); 
    2453}; 
    2554 
     55/** \cond */ 
    2656extern struct HYDT_bsci_fns HYDT_bsci_fns; 
     57extern struct HYDT_bsci_info HYDT_bsci_info; 
     58/** \endcond */ 
    2759 
     60/** 
     61 * \brief HYDT_bsci_init - Initialize the bootstrap control device 
     62 * 
     63 * \param[in]   bootstrap       Bootstrap device to use 
     64 * \param[in]   bootstrap_exec  Bootstrap helper executable to use (optional) 
     65 * \param[in]   enablex         Enable/disable X-forwarding (hint only) 
     66 * \param[in]   debug           Enable/disable debugging 
     67 * 
     68 * This function initializes the bootstrap control device. This needs 
     69 * to be called before any other BSCI function. Implementors are 
     70 * expected to set any bootstrap implementation specific function 
     71 * pointers in this function to be used by later BSCI calls. 
     72 */ 
    2873HYD_status HYDT_bsci_init(char *bootstrap, char *bootstrap_exec, int enablex, int debug); 
     74 
     75 
     76/** 
     77 * \brief HYDT_bsci_launch_procs - Launch processes 
     78 * 
     79 * \param[in]   global_args     Arguments to be used for the launched processes 
     80 * \param[in]   proxy_id_str    String to prepend in the arguments for the 
     81 *                              proxy ID (use -1 if the proxy should query for the ID) 
     82 * \param[in]   proxy_list      List of proxy structures containing the list of hosts 
     83 * 
     84 * This function uses the hosts information in the proxy_list to 
     85 * launch processes. Bootstrap servers that perform sequential 
     86 * launches (one process at a time), should set the proxy ID string in 
     87 * sequential order. Bootstrap servers that perform parallel launches 
     88 * should set the proxy ID string to "-1", but allow proxies to query 
     89 * their ID information on each node using the 
     90 * HYDT_bsci_query_proxy_id function. 
     91 */ 
    2992HYD_status HYDT_bsci_launch_procs(char **global_args, const char *proxy_id_str, 
    3093                                 struct HYD_proxy *proxy_list); 
     94 
     95 
     96/** 
     97 * \brief HYDT_bsci_finalize - Finalize the bootstrap control device 
     98 * 
     99 * This function cleans up any relevant state that the bootstrap 
     100 * device maintained. 
     101 */ 
    31102HYD_status HYDT_bsci_finalize(void); 
     103 
     104 
     105/** 
     106 * \brief HYDT_bsci_wait_for_completion - Wait for bootstrap launched processes to complete 
     107 * 
     108 * \param[in]   proxy_list      List of proxy structures containing the list of hosts 
     109 * 
     110 * This function waits for all processes it launched to finish. The 
     111 * bootstrap control device should keep track of the processes it is 
     112 * launching and wait for their completion. 
     113 */ 
    32114HYD_status HYDT_bsci_wait_for_completion(struct HYD_proxy *proxy_list); 
     115 
     116 
     117/** 
     118 * \brief HYDT_bsci_query_node_list - Query for node list information 
     119 * 
     120 * \param[in,out] num_cores       Number of cores available (non-zero value refers to 
     121 *                                a request to allocate nodes/cores) 
     122 * \param[in]     proxy_list      List of proxy structures containing the list of hosts 
     123 * 
     124 * This function allows the upper layers to query the available nodes 
     125 * or request for nodes to be allocated (non-zero value refers to a 
     126 * request to allocate nodes/cores). 
     127 */ 
    33128HYD_status HYDT_bsci_query_node_list(int *num_cores, struct HYD_proxy **proxy_list); 
     129 
     130 
     131/** 
     132 * \brief HYDT_bsci_query_usize - Query for the universe size 
     133 * 
     134 * \param[out]  size       Maximum number of processes that can be launched 
     135 * 
     136 * If the underlying system allows for multitasking many processes on 
     137 * a single processing element, the bootstrap server should return 
     138 * "-1" (representing infinite). If not, it should specify the number 
     139 * of processes that can be spawned. 
     140 */ 
    34141HYD_status HYDT_bsci_query_usize(int *size); 
     142 
     143 
     144/** 
     145 * \brief HYDT_bsci_query_proxy_id - Query the ID of a proxy 
     146 * 
     147 * \param[out]  proxy_id    My proxy ID 
     148 * 
     149 * This function is called by each proxy if the proxy_str_id is 
     150 * specified as "-1" during launch. 
     151 */ 
    35152HYD_status HYDT_bsci_query_proxy_id(int *proxy_id); 
     153 
     154/*! @} */ 
    36155 
    37156/* Each bootstrap server has to expose an initialization function */ 
    38157@hydra_bss_init_decl@ 
    39158 
    40 extern struct HYDT_bsci_info HYDT_bsci_info; 
    41  
    42159#endif /* BSCI_H_INCLUDED */ 

  • mpich2/trunk/src/pm/hydra/tools/ckpoint/ckpoint.h

    r5698 r5708  
    88#define CKPOINT_H_INCLUDED 
    99 
     10/** @file ckpoint.h */ 
     11 
    1012#include "hydra_utils.h" 
    1113 
     14/*! \addtogroup ckpoint Checkpointing Library Interface 
     15 * @{ 
     16 */ 
     17 
     18/** 
     19 * \brief Checkpointing information 
     20 * 
     21 * Contains private persistent information stored by the checkpointing 
     22 * library. 
     23 */ 
    1224struct HYDT_ckpoint_info { 
     25    /** \brief Checkpointing library to use */ 
    1326    char *ckpointlib; 
     27 
     28    /** \brief Storage prefix for where to store checkpointing files 
     29     * and other associated meta-data */ 
    1430    char *ckpoint_prefix; 
    1531}; 
    1632 
     33/** \cond */ 
    1734extern struct HYDT_ckpoint_info HYDT_ckpoint_info; 
     35/** \endcond */ 
    1836 
     37/** 
     38 * \brief HYDT_ckpoint_init - Initialize the checkpointing library 
     39 * 
     40 * \param[in]  ckpointlib      Checkpointing library to use 
     41 * \param[in]  ckpoint_prefix  Storage prefix for where to store checkpointing files 
     42 * 
     43 * This function initializes the checkpointing library requested by 
     44 * the user. 
     45 */ 
    1946HYD_status HYDT_ckpoint_init(char *ckpointlib, char *ckpoint_prefix); 
     47 
     48 
     49/** 
     50 * \brief HYDT_ckpoint_suspend - Initiate suspend of child processes 
     51 * 
     52 * This function is called by a proxy to suspend all of its child 
     53 * processes. 
     54 */ 
    2055HYD_status HYDT_ckpoint_suspend(void); 
     56 
     57 
     58/** 
     59 * \brief HYDT_ckpoint_restart - Restart child processes 
     60 * 
     61 * \param[in] envlist    Environment setup from before the checkpoint 
     62 * \param[in] num_ranks  Number of child processes to restart 
     63 * \param[in] ranks      Array of ranks of the child processes 
     64 * \param[in] in         stdin sockets from before the checkpoint 
     65 * \param[in] out        stdout sockets from before the checkpoint 
     66 * \param[in] err        stderr sockets from before the checkpoint 
     67 * 
     68 * This function is called by a proxy to restart all its child 
     69 * processes. Stdin, stdout and stderr connections are 
     70 * reestablished. The environment passed in this list is resetup for 
     71 * each process. 
     72 */ 
    2173HYD_status HYDT_ckpoint_restart(HYD_env_t * envlist, int num_ranks, int ranks[], int *in, 
    2274                                int *out, int *err); 
    2375 
     76/*! 
     77 * @} 
     78 */ 
     79 
    2480#endif /* CKPOINT_H_INCLUDED */ 

  • mpich2/trunk/src/pm/hydra/tools/demux/demux.h

    r5472 r5708  
    88#define DEMUX_H_INCLUDED 
    99 
     10/** @file demux.h */ 
     11 
    1012#include "hydra.h" 
    1113 
     14/*! \addtogroup demux Demultiplexing Engine 
     15 * @{ 
     16 */ 
     17 
     18/** 
     19 * \brief HYDT_dmx_register_fd - Register file descriptors for events 
     20 * 
     21 * \param[in]  num_fds  Number of file descriptors being provided 
     22 * \param[in]  fd       Array of file descriptors 
     23 * \param[in]  events   Events we are interested in 
     24 * \param[in]  userp    Persistent user storage associated with a descriptor 
     25 *                      (not interpreted by the demux engine) 
     26 * \param[in]  callback Callback function to call when the event occurs 
     27 * 
     28 * This function registers all file descriptors to be waited on for an 
     29 * event. 
     30 */ 
    1231HYD_status HYDT_dmx_register_fd(int num_fds, int *fd, HYD_event_t events, void *userp, 
    1332                                HYD_status(*callback) (int fd, HYD_event_t events, 
    1433                                                       void *userp)); 
     34 
     35/** 
     36 * \brief HYDT_dmx_deregister_fd - Deregister file descriptor 
     37 * 
     38 * \param[in]   fd    File descriptor to be deregistered 
     39 * 
     40 * This function deregisters a file descriptor from the demux 
     41 * engine. All registered fd's must be deregistered. 
     42 */ 
    1543HYD_status HYDT_dmx_deregister_fd(int fd); 
     44 
     45/** 
     46 * \brief HYDT_dmx_wait_for_event - Wait for event 
     47 * 
     48 * \param    time      Time to wait for in millisecond (-1 means infinite) 
     49 * 
     50 * This function waits till either one of the registered fd's has had 
     51 * one of its registered events, or till the timeout expires. 
     52 */ 
    1653HYD_status HYDT_dmx_wait_for_event(int time); 
     54 
     55/** 
     56 * \brief HYDT_dmx_finalize - Finalize demux engine 
     57 * 
     58 * This function cleans up any relevant state that the demux engine 
     59 * maintained. 
     60 */ 
    1761HYD_status HYDT_dmx_finalize(void); 
    1862 
     63/*! 
     64 * @} 
     65 */ 
     66 
    1967#endif /* DEMUX_H_INCLUDED */