Commit f8cf79d6 authored by PRUVOST Florent's avatar PRUVOST Florent

first step for a doxygen doc for developers

parent 7ca01e2b
......@@ -28,6 +28,28 @@
**/
#include "control/common.h"
/**
*
* @defgroup MORSE_Complex64_t
* @brief Linear algebra routines exposed to users. LAPACK matrix data storage
*
*/
/**
*
* @defgroup MORSE_Complex64_t_Tile
* @brief Linear algebra routines exposed to users. Tile matrix data storage
*
*/
/**
*
* @defgroup MORSE_Complex64_t_Tile_Async
* @brief Linear algebra routines exposed to users. Tile matrix data storage,
* asynchronous interface.
*
*/
/***************************************************************************//**
*
* @ingroup MORSE_Complex64_t
......
......@@ -51,29 +51,19 @@ set(CHAMELEON_HDRS
morsewinthread.h
tile.h
workspace.h
${CHAMELEON_HDRS_GENERATED}
)
set(HDR_INSTALL ${CHAMELEON_HDRS})
foreach( hdr_file ${CHAMELEON_HDRS_GENERATED} )
list(APPEND HDR_INSTALL ${CMAKE_CURRENT_BINARY_DIR}/${hdr_file})
endforeach()
list(APPEND CHAMELEON_HDRS ${CHAMELEON_HDRS_GENERATED})
# Force generation of headers
# ---------------------------
add_custom_target(control_include ALL SOURCES ${CHAMELEON_HDRS})
set(HDR_INSTALL
async.h
auxiliary.h
bulge.h
common.h
context.h
descriptor.h
gkkleader.h
global.h
morsewinthread.h
tile.h
workspace.h
)
foreach( hdr_file ${CHAMELEON_HDRS_GENERATED} )
list(APPEND HDR_INSTALL ${CMAKE_CURRENT_BINARY_DIR}/${hdr_file})
endforeach()
# installation
# ------------
......
......@@ -23,6 +23,14 @@
* @date 2012-09-15
*
**/
/**
*
* @defgroup Sequences
* @brief Group routines exposed to users to handle asynchronous tasks execution
*
*/
#include <stdlib.h>
#include "control/common.h"
#include "runtime.h"
......@@ -73,23 +81,23 @@ int morse_sequence_wait(MORSE_context_t *morse, MORSE_sequence_t *sequence)
return MORSE_SUCCESS;
}
/*******************************************************************************
/** ***************************************************************************
*
* @ingroup Auxiliary
* @ingroup Sequences
*
* MORSE_Sequence_Create - Create a squence.
*
*******************************************************************************
******************************************************************************
*
* @param[out] sequence
* Identifies a set of routines sharing common exception handling.
*
*******************************************************************************
******************************************************************************
*
* @return
* \retval MORSE_SUCCESS successful exit
*
******************************************************************************/
*****************************************************************************/
int MORSE_Sequence_Create(MORSE_sequence_t **sequence)
{
MORSE_context_t *morse;
......@@ -104,23 +112,23 @@ int MORSE_Sequence_Create(MORSE_sequence_t **sequence)
return status;
}
/*******************************************************************************
/** ***************************************************************************
*
* @ingroup Auxiliary
* @ingroup Sequences
*
* MORSE_Sequence_Destroy - Destroy a sequence.
*
*******************************************************************************
******************************************************************************
*
* @param[in] sequence
* Identifies a set of routines sharing common exception handling.
*
*******************************************************************************
******************************************************************************
*
* @return
* \retval MORSE_SUCCESS successful exit
*
******************************************************************************/
*****************************************************************************/
int MORSE_Sequence_Destroy(MORSE_sequence_t *sequence)
{
MORSE_context_t *morse;
......@@ -139,23 +147,23 @@ int MORSE_Sequence_Destroy(MORSE_sequence_t *sequence)
return status;
}
/*******************************************************************************
/** ***************************************************************************
*
* @ingroup Auxiliary
* @ingroup Sequences
*
* MORSE_Sequence_Wait - Wait for the completion of a sequence.
*
*******************************************************************************
******************************************************************************
*
* @param[in] sequence
* Identifies a set of routines sharing common exception handling.
*
*******************************************************************************
******************************************************************************
*
* @return
* \retval MORSE_SUCCESS successful exit
*
******************************************************************************/
*****************************************************************************/
int MORSE_Sequence_Wait(MORSE_sequence_t *sequence)
{
MORSE_context_t *morse;
......@@ -174,13 +182,13 @@ int MORSE_Sequence_Wait(MORSE_sequence_t *sequence)
return status;
}
/******************************************************************************
/** ***************************************************************************
*
* @ingroup Auxiliary
* @ingroup Sequences
*
* MORSE_Sequence_Flush - Terminate a sequence.
*
*******************************************************************************
******************************************************************************
*
* @param[in] sequence
* Identifies a set of routines sharing common exception handling.
......@@ -188,12 +196,12 @@ int MORSE_Sequence_Wait(MORSE_sequence_t *sequence)
* @param[in] request
* The flush request.
*
*******************************************************************************
******************************************************************************
*
* @return
* \retval MORSE_SUCCESS successful exit
*
******************************************************************************/
*****************************************************************************/
int MORSE_Sequence_Flush(MORSE_sequence_t *sequence, MORSE_request_t *request)
{
MORSE_context_t *morse;
......
......@@ -24,6 +24,14 @@
* @date 2012-09-15
*
**/
/**
*
* @defgroup Auxiliary
* @brief Group auxiliary routines exposed to users
*
*/
#include "control/common.h"
#include "control/auxiliary.h"
......@@ -100,24 +108,6 @@ void morse_fatal_error(const char *func_name, char* msg_text)
exit(0);
}
/*******************************************************************************
*
**/
int morse_element_size(int type)
{
switch(type) {
case MorseByte: return 1;
case MorseInteger: return sizeof(int);
case MorseRealFloat: return sizeof(float);
case MorseRealDouble: return sizeof(double);
case MorseComplexFloat: return 2*sizeof(float);
case MorseComplexDouble: return 2*sizeof(double);
default: morse_fatal_error("morse_element_size", "undefined type");
return MORSE_ERR_ILLEGAL_VALUE;
}
}
/*******************************************************************************
* Returns core id
**/
......@@ -139,13 +129,13 @@ int morse_tune(MORSE_enum func, int M, int N, int NRHS)
return MORSE_SUCCESS;
}
/*******************************************************************************
/** ***************************************************************************
*
* @ingroup Auxiliary
*
* MORSE_Version - Reports MORSE version number.
*
*******************************************************************************
******************************************************************************
*
* @param[out] ver_major
* MORSE major version number.
......@@ -156,12 +146,12 @@ int morse_tune(MORSE_enum func, int M, int N, int NRHS)
* @param[out] ver_micro
* MORSE micro version number.
*
*******************************************************************************
******************************************************************************
*
* @return
* \retval MORSE_SUCCESS successful exit
*
******************************************************************************/
*****************************************************************************/
int MORSE_Version(int *ver_major, int *ver_minor, int *ver_micro)
{
if (! ver_major && ! ver_minor && ! ver_micro)
......@@ -178,3 +168,70 @@ int MORSE_Version(int *ver_major, int *ver_minor, int *ver_micro)
return MORSE_SUCCESS;
}
/** ***************************************************************************
*
* @ingroup Auxiliary
*
* MORSE_Element_Size - Reports the size in bytes of a MORSE precision type
* (e.g. MorseInteger, MorseRealFloat, etc).
*
******************************************************************************
*
* @param[in] type
* MORSE element type, can be one of the following:
* - MorseByte
* - MorseInteger
* - MorseRealFloat
* - MorseRealDouble
* - MorseComplexFloat
* - MorseComplexDouble
*
******************************************************************************
*
* @return
* \retval Element size in bytes
*
*****************************************************************************/
int MORSE_Element_Size(int type)
{
switch(type) {
case MorseByte: return 1;
case MorseInteger: return sizeof(int);
case MorseRealFloat: return sizeof(float);
case MorseRealDouble: return sizeof(double);
case MorseComplexFloat: return 2*sizeof(float);
case MorseComplexDouble: return 2*sizeof(double);
default: morse_fatal_error("MORSE_Element_Size", "undefined type");
return MORSE_ERR_ILLEGAL_VALUE;
}
}
/** ***************************************************************************
*
* @ingroup Auxiliary
*
* MORSE_My_Mpi_Rank - Return the MPI rank of the calling process.
*
******************************************************************************
*
******************************************************************************
*
* @return
* \retval MPI rank
*
*****************************************************************************/
int MORSE_My_Mpi_Rank(void)
{
#if defined(CHAMELEON_USE_MPI)
MORSE_context_t *morse = morse_context_self();
if (morse == NULL) {
morse_error("MORSE_Finalize()", "MORSE not initialized");
return MORSE_ERR_NOT_INITIALIZED;
}
return MORSE_MPI_RANK;
#else
return MORSE_SUCCESS;
#endif
}
......@@ -39,15 +39,9 @@ extern "C" {
void morse_warning (const char *func_name, char* msg_text);
void morse_error (const char *func_name, char* msg_text);
void morse_fatal_error (const char *func_name, char* msg_text);
int morse_element_size (int type);
int morse_rank (MORSE_context_t *morse);
int morse_tune (MORSE_enum func, int M, int N, int NRHS);
/*******************************************************************************
* User routines
**/
int MORSE_Version (int *ver_major, int *ver_minor, int *ver_micro);
#ifdef __cplusplus
}
#endif
......
......@@ -24,6 +24,13 @@
*
**/
/**
*
* @defgroup Options
* @brief Group routines exposed to users to handle options
*
*/
#include <stdlib.h>
#if defined( _WIN32 ) || defined( _WIN64 )
#include "control/morsewinthread.h"
......@@ -109,15 +116,15 @@ int morse_context_destroy(){
return MORSE_SUCCESS;
}
/*******************************************************************************
/** ***************************************************************************
*
* @ingroup Auxiliary
* @ingroup Options
*
* MORSE_Enable - Enable MORSE feature.
*
*******************************************************************************
*
* @param[in] lever
* @param[in] option
* Feature to be enabled:
* @arg MORSE_WARNINGS printing of warning messages,
* @arg MORSE_ERRORS printing of error messages,
......@@ -170,15 +177,15 @@ int MORSE_Enable(MORSE_enum option)
return MORSE_SUCCESS;
}
/*******************************************************************************
/** ***************************************************************************
*
* @ingroup Auxiliary
* @ingroup Options
*
* MORSE_Disable - Disable MORSE feature.
*
*******************************************************************************
*
* @param[in] lever
* @param[in] option
* Feature to be disabled:
* @arg MORSE_WARNINGS printing of warning messages,
* @arg MORSE_ERRORS printing of error messages,
......@@ -228,9 +235,9 @@ int MORSE_Disable(MORSE_enum option)
return MORSE_SUCCESS;
}
/*******************************************************************************
/** ***************************************************************************
*
* @ingroup Auxiliary
* @ingroup Options
*
* MORSE_Set - Set MORSE parameter.
*
......@@ -322,9 +329,9 @@ int MORSE_Set(MORSE_enum param, int value)
return MORSE_SUCCESS;
}
/*******************************************************************************
/** ***************************************************************************
*
* @ingroup Auxiliary
* @ingroup Options
*
* MORSE_Get - Get value of MORSE parameter.
*
......
......@@ -23,63 +23,69 @@
* @date 2012-09-15
*
**/
/**
*
* @defgroup Control
* @brief Group routines exposed to users to control MORSE state
*
*/
#include <stdio.h>
#include <stdlib.h>
#include "control/auxiliary.h"
#include "control/common.h"
#include "runtime.h"
/*******************************************************************************
/** ***************************************************************************
*
* @ingroup Auxiliary
* @ingroup Control
*
* MORSE_Init - Initialize MORSE.
*
*******************************************************************************
******************************************************************************
*
* @param[in] cores
* Number of cores to use (threads to launch).
* If cores = 0, cores = MORSE_NUM_THREADS if it is set, the
* system number of core otherwise.
* Number of cores to use.
*
*******************************************************************************
* @param[in] gpus
* Number of cuda devices to use.
*
******************************************************************************
*
* @return
* \retval MORSE_SUCCESS successful exit
*
******************************************************************************/
*****************************************************************************/
int MORSE_Init(int cores, int gpus)
{
return MORSE_InitPar(cores, gpus, -1);
}
/*******************************************************************************
/** ***************************************************************************
*
* @ingroup Auxiliary
* @ingroup Control
*
* MORSE_Init_Affinity - Initialize MORSE.
* MORSE_InitPar - Initialize MORSE.
*
*******************************************************************************
******************************************************************************
*
* @param[in] cores
* Number of cores to use (threads to launch).
* If cores = 0, cores = MORSE_NUM_THREADS if it is set, the
* system number of core otherwise.
* @param[in] ncpus
* Number of cores to use.
*
* @param[in] coresbind
* Array to specify where to bind each thread.
* Each thread i is binded to coresbind[hwloc(i)] if hwloc is
* provided, or to coresbind[i] otherwise.
* If coresbind = NULL, coresbind = MORSE_AFF_THREADS if it
* is set, the identity function otherwise.
* @param[in] ncudas
* Number of cuda devices to use.
*
*******************************************************************************
* @param[in] nthreads_per_worker
* Number of threads per worker (cpu, cuda device).
*
******************************************************************************
*
* @return
* \retval MORSE_SUCCESS successful exit
*
******************************************************************************/
int MORSE_InitPar(int nworkers, int ncudas, int nthreads_per_worker)
*****************************************************************************/
int MORSE_InitPar(int ncpus, int ncudas, int nthreads_per_worker)
{
MORSE_context_t *morse;
......@@ -90,33 +96,6 @@ int MORSE_InitPar(int nworkers, int ncudas, int nthreads_per_worker)
return MORSE_ERR_OUT_OF_RESOURCES;
}
#if 0
/* Init number of cores and topology */
morse_topology_init();
/* Set number of nworkers */
if ( nworkers < 1 ) {
morse->world_size = morse_get_numthreads();
if ( morse->world_size == -1 ) {
morse->world_size = 1;
morse_warning("MORSE_Init", "Could not find the number of cores: the thread number is set to 1");
}
}
else
morse->world_size = nworkers;
if (morse->world_size <= 0) {
morse_fatal_error("MORSE_Init", "failed to get system size");
return MORSE_ERR_NOT_FOUND;
}
nworkers = morse->world_size;
/* Get the size of each NUMA node */
morse->group_size = morse_get_numthreads_numa();
while ( ((morse->world_size)%(morse->group_size)) != 0 )
(morse->group_size)--;
#endif
#if defined(CHAMELEON_USE_MPI)
{
int flag = 0, provided = 0;
......@@ -130,22 +109,22 @@ int MORSE_InitPar(int nworkers, int ncudas, int nthreads_per_worker)
#if defined(CHAMELEON_USE_MAGMA)
magma_init();
#endif
RUNTIME_init_scheduler( morse, nworkers, ncudas, nthreads_per_worker );
RUNTIME_init_scheduler( morse, ncpus, ncudas, nthreads_per_worker );
return MORSE_SUCCESS;
}
/*******************************************************************************
/** ***************************************************************************
*
* @ingroup Auxiliary
* @ingroup Control
*
* MORSE_Finalize - Finalize MORSE.
*
*******************************************************************************
******************************************************************************
*
* @return
* \retval MORSE_SUCCESS successful exit
*
******************************************************************************/
*****************************************************************************/
int MORSE_Finalize(void)
{
MORSE_context_t *morse = morse_context_self();
......@@ -168,46 +147,18 @@ int MORSE_Finalize(void)
return MORSE_SUCCESS;
}
/*******************************************************************************
*
* @ingroup Auxiliary
*
* MORSE_My_Mpi_Rank - Return the MPI rank of the calling process.
*
*******************************************************************************
*
*******************************************************************************
*
* @return
* \retval MPI rank
*
******************************************************************************/
int MORSE_My_Mpi_Rank(void)
{
#if defined(CHAMELEON_USE_MPI)
MORSE_context_t *morse = morse_context_self();
if (morse == NULL) {
morse_error("MORSE_Finalize()", "MORSE not initialized");
return MORSE_ERR_NOT_INITIALIZED;
}
return MORSE_MPI_RANK;
#else
return MORSE_SUCCESS;
#endif
}
/*******************************************************************************
/** ***************************************************************************
*
* @ingroup Auxiliary
* @ingroup Control
*
* MORSE_Pause - Suspend MORSE runtime to poll for new tasks.
*
*******************************************************************************
******************************************************************************
*
* @return
* \retval MORSE_SUCCESS successful exit
*
******************************************************************************/
*****************************************************************************/
int MORSE_Pause(void)
{
MORSE_context_t *morse = morse_context_self();
......@@ -219,19 +170,19 @@ int MORSE_Pause(void)
return MORSE_SUCCESS;
}
/*******************************************************************************
/** ***************************************************************************
*
* @ingroup Auxiliary
* @ingroup Control
*
* MORSE_Resume - Symmetrical call to MORSE_Pause,
* used to resume the workers polling for new tasks.
*
*******************************************************************************
******************************************************************************
*
* @return
* \retval MORSE_SUCCESS successful exit
*
******************************************************************************/
*****************************************************************************/
int MORSE_Resume(void)
{
MORSE_context_t *morse = morse_context_self();
......
......@@ -22,6 +22,14 @@
* @date 2010-11-15
*
**/
/**
*
* @defgroup Descriptor
* @brief Group descriptor routines exposed to users
*
*/
#include <stdlib.h>
#include <assert.h>
#include "control/common.h"
......@@ -299,7 +307,7 @@ int morse_desc_mat_alloc( MORSE_desc_t *desc )
{
size_t size = (size_t)(desc->llm) * (size_t)(desc->lln)
* (size_t)morse_element_size(desc->dtyp);
* (size_t)MORSE_Element_Size(desc->dtyp);
if ((desc->mat = malloc(size)) == NULL) {
morse_error("morse_desc_mat_alloc", "malloc() failed");
return MORSE_ERR_OUT_OF_RESOURCES;
......@@ -329,13 +337,13 @@ int morse_desc_mat_free( MORSE_desc_t *desc )
return MORSE_SUCCESS;
}
/*******************************************************************************
/** ***************************************************************************
*
* @ingroup Auxiliary
* @ingroup Descriptor
*
* MORSE_Desc_Create - Create matrix descriptor.
*
*******************************************************************************
******************************************************************************
*
* @param[out] desc
* On exit, descriptor of the matrix.
......@@ -378,12 +386,12 @@ int morse_desc_mat_free( MORSE_desc_t *desc )
* @param[in] n
* Number of columns of the submatrix.
*
*******************************************************************************
******************************************************************************
*
* @return
* \retval MORSE_SUCCESS successful exit
*
******************************************************************************/
*****************************************************************************/
int MORSE_Desc_Create(MORSE_desc_t **desc, void *mat, MORSE_enum dtyp, int mb, int nb, int bsiz,
int lm, int ln, int i, int j, int m, int n, int p, int q)
{
......@@ -411,7 +419,7 @@ int MORSE_Desc_Create(MORSE_desc_t **desc, void *mat, MORSE_enum dtyp, int mb, i
/* TODO: a call to morse_desc_mat_alloc should be made, but require to
move the call to RUNTIME_desc_create within the function */
size_t size = (size_t)((*desc)->llm) * (size_t)((*desc)->lln)
* (size_t)morse_element_size((*desc)->dtyp);
* (size_t)MORSE_Element_Size((*desc)->dtyp);
if (((**desc).mat = malloc(size)) == NULL) {
morse_error("MORSE_Desc_Create", "malloc() failed");
......@@ -437,13 +445,13 @@ int MORSE_Desc_Create(MORSE_desc_t **desc, void *mat, MORSE_enum dtyp, int mb, i
return MORSE_SUCCESS;
}
/*******************************************************************************
/** ***************************************************************************
*
* @ingroup Auxiliary
* @ingroup Descriptor
*
* MORSE_Desc_Create_User - Create matrix descriptor for general applications.
*
*******************************************************************************
******************************************************************************
*
* @param[out] desc
* On exit, descriptor of the matrix.
......@@ -484,12 +492,12 @@ int MORSE_Desc_Create(MORSE_desc_t **desc, void *mat, MORSE_enum dtyp, int mb, i
* @param[in] (*get_rankof)( const MORSE_desc_t *A, int m, int n)
* A function that return the MPI rank of the tile A(m,n).
*
*******************************************************************************
******************************************************************************
*
* @return
* \retval MORSE_SUCCESS successful exit
*
******************************************************************************/
*****************************************************************************/
int MORSE_Desc_Create_User(MORSE_desc_t **desc, void *mat, MORSE_enum dtyp, int mb, int nb, int bsiz,
int lm, int ln, int i, int j, int m, int n, int p, int q,
void* (*get_blkaddr)( const MORSE_desc_t*, int,