Add some comments to libhqr.h and add cmake files

CMakeLists.txt

+###
+#
+#  @copyright 2017      Bordeaux INP, CNRS (LaBRI UMR 5800), Inria,
+#                       Univ. Bordeaux. All rights reserved.
+#
+#  @version 0.1.0
+#  @author Mathieu Faverge
+#  @date 2017-04-26
+#
+###
+cmake_minimum_required (VERSION 3.0)
+project (LIBHQR C)
+
+# The current version number
+set (LIBHQR_VERSION_MAJOR 0)
+set (LIBHQR_VERSION_MINOR 1)
+set (LIBHQR_VERSION_MICRO 0)
+
+set( LIBHQR_VERSION "${LIBHQR_VERSION_MAJOR}.${LIBHQR_VERSION_MINOR}.${LIBHQR_VERSION_MICRO}" )
+
+### Misc options
+option(BUILD_SHARED_LIBS
+  "Build shared libraries" OFF)
+if(NOT CMAKE_BUILD_TYPE)
+  set(CMAKE_BUILD_TYPE RelWithDebInfo CACHE STRING "Choose the type of build, options are None, Debug, Release, RelWithDebInfo and MinSizeRel." FORCE)
+endif(NOT CMAKE_BUILD_TYPE)
+
+set(hdrs
+  include/common.h
+  include/libdraw.h
+  include/libhqr.h
+  include/queue.h
+)
+set(srcs
+  src/libhqr.c
+  src/libhqr_dbg.c
+  src/libhqr_systolic.c
+  src/queue.c
+  src/treedraw.c
+  src/treewalk.c
+)
+
+include_directories(include)
+add_library(hqr ${srcs})
+target_link_libraries( hqr m )
+
+add_subdirectory(testings)
+
+install(FILES
+  include/libhqr.h
+  include/libhqr_dbg.h
+  DESTINATION include )
+
+#-- Add a custom target to generate tags
+add_custom_target (tags
+  COMMAND "git ls-files | xargs etags" )

include/libhqr.h

@@ -36,7 +36,7 @@ static inline int libhqr_iceil(int a, int b){
 }
 
 /**
- * @brief Define to which tree level the tile belongs to.
+ * @brief Define which tree level the tile belongs to.
  *
  * Four levels of trees are available:
  *   - The top one (LIBHQR_KILLED_BY_DISTTREE) is meant to be the communication
@@ -49,8 +49,9 @@ static inline int libhqr_iceil(int a, int b){
  *     the local trees in order to generate a better pipeline for tall and skinny
  *     matrices.
  *
- * @remark LIBHQR_KILLED_BY_TS needs to be stay 0 for all variant of QR
- * factorizations in order to distinguish TT kernels from TS kernels in compuations
+ * @remark LIBHQR_KILLED_BY_TS needs to be 0 for all variant of QR
+ * factorizations in order to distinguish TT kernels from TS kernels in
+ * compuations
  *
  */
 typedef enum libhqr_type_ {
@@ -62,6 +63,10 @@ typedef enum libhqr_type_ {
 
 /**
  * @brief Define the type of trees that can be used for the reduction.
+ *
+ * These are the kind of trees available for low-level reduction in shared
+ * memory, or for high-level reduction in distributed memory. Note that all
+ * kinds of trees are not available for both levels.
  */
 typedef enum libhqr_tree_ {
     LIBHQR_FLAT_TREE      = 0,
@@ -75,18 +80,18 @@ typedef enum libhqr_tree_ {
  * @brief Define the type of factorization to apply: QR or LQ.
  */
 typedef enum libhqr_typefacto_ {
-    LIBHQR_QR = 0,
-    LIBHQR_LQ = 1,
+    LIBHQR_QR = 0,     /**< QR factorization will be performed, and A shape is considered   */
+    LIBHQR_LQ = 1,     /**< LQ factorization will be performed, and A^t shape is considered */
 } libhqr_typefacto_e;
 
 /**
  * @brief Minimal structure to define the shape of the matrix to factorize.
  */
 typedef struct libhqr_tiledesc_s{
-    int mt;    /**< The number of rows of tiles                             */
-    int nt;    /**< The number of columns of tiles                          */
-    int nodes; /**< The number of nodes involved in the data distribution   */
-    int p;     /**< The number of nodes per column in the data distribution */
+    int mt;            /**< The number of rows of tiles                             */
+    int nt;            /**< The number of columns of tiles                          */
+    int nodes;         /**< The number of nodes involved in the data distribution   */
+    int p;             /**< The number of nodes per column in the data distribution */
 } libhqr_tiledesc_t;
 
 
@@ -107,6 +112,9 @@ typedef struct libhqr_tree_s libhqr_tree_t;
 
 typedef struct libhqr_context_s libhqr_context_t;
 
+/**
+ * @brief Hierarchical tree structure for QR/LQ factorization like kernels.
+ */
 struct libhqr_tree_s {
     /**
      * @brief Return the number of geqrt/gelqt kernels in the column/row k
@@ -178,15 +186,17 @@ struct libhqr_tree_s {
      */
     int (*prevpiv)(const libhqr_tree_t *qrtree, int k, int p, int m);
 
-    /** Descriptor infos associated to the factorization */
-    int mt;
-    int nt;
-    /** Size of the domain where TS kernels are applied */
-    int a;
-    /** Size of highest level tree (distributed one) */
-    int p;
-    int domino;
-    void *args;
+    int mt;     /**< Number of rows of tile A if QR factorization, and in A^t if LQ
+                     factorization                                                   */
+    int nt;     /**< Number of tile reflectors to compute. This is equal to
+                     min(A->mt, A->nt)                                               */
+    int a;      /**< Size of the local flat TS trees                                 */
+    int p;      /**< Size of the highest level tree (distributed one), recommended
+                     to be the number of process rows in the 2D-cyclic distribution  */
+    int domino; /**< Enable the domino tree to connect high and low level trees
+                     in T&S matrices                                                 */
+    void *args; /**< Arguments of the qrtree structure (depends on the kind of
+                     tree: hqr, systolic, svd, ...)                                  */
 };
 
 int  libhqr_systolic_init( libhqr_tree_t *qrtree,

testings/CMakeLists.txt

+###
+#
+#  @copyright 2017      Bordeaux INP, CNRS (LaBRI UMR 5800), Inria,
+#                       Univ. Bordeaux. All rights reserved.
+#
+#  @version 0.1.0
+#  @author Mathieu Faverge
+#  @date 2017-04-26
+#
+###
+set(TESTINGS
+  testing_pivgen.c
+  testing_tileinit.c
+  testing_treedraw.c
+  )
+
+foreach (_file ${TESTINGS})
+  get_filename_component(_name_we ${_file} NAME_WE)
+  add_executable(${_name_we} ${_file})
+  target_link_libraries(${_name_we} hqr)
+
+  install(TARGETS ${_name_we} RUNTIME DESTINATION examples )
+  install(FILES   ${_file}            DESTINATION examples )
+
+endforeach()