From ba555a3eaecf5d45b55d42e451197c2badbca7dd Mon Sep 17 00:00:00 2001
From: Emilien Bauer <emilien.bauer@etu.unistra.fr>
Date: Wed, 16 Jun 2021 14:27:52 +0200
Subject: [PATCH] Doxygen population
---
CMakeLists.txt | 27 ++++----
README.md | 2 +-
back/periscop/helpers/farkas.c | 1 +
back/periscop/helpers/farkas.h | 95 +++++++++++++++++---------
back/periscop/helpers/osl_to_polylib.h | 29 +++++++-
back/periscop/helpers/utils.h | 53 +++++++++++++-
doxygen.h | 13 ++++
front/ast.cpp | 2 +
front/ast.hpp | 36 +++++++++-
9 files changed, 206 insertions(+), 52 deletions(-)
create mode 100644 doxygen.h
diff --git a/CMakeLists.txt b/CMakeLists.txt
index b77eaa1..7cd70c6 100644
--- a/CMakeLists.txt
+++ b/CMakeLists.txt
@@ -3,9 +3,6 @@ project(PolyLingual
VERSION 0.0.2
LANGUAGES CXX C)
-#Include for ExternalProjet_Add, to include AutoTools project
-include(ExternalProject)
-
#Add this project's module path
list(APPEND CMAKE_MODULE_PATH "${CMAKE_SOURCE_DIR}/CMake")
#include the GenGen-related functions
@@ -23,6 +20,20 @@ if(${DOXYGEN_FOUND})
${CMAKE_CURRENT_BINARY_DIR}/front/*
*.y
*.l)
+ set(DOXYGEN_BUILTIN_STL_SUPPORT YES)
+ set(DOXYGEN_GENERATE_TREEVIEW YES)
+ set(DOXYGEN_REPEAT_BRIEF NO)
+ set(DOXYGEN_USE_MATHJAX YES)
+ set(DOXYGEN_EXTRACT_STATIC YES)
+ set(DOXYGEN_SOURCE_BROWSER YES)
+ set(DOXYGEN_REFERENCED_BY_RELATION YES)
+ set(DOXYGEN_REFERENCES_RELATION YES)
+ set(DOXYGEN_REFERENCES_LINK_SOURCE NO)
+ set(DOXYGEN_ENUM_VALUES_PER_LINE 1)
+ set(DOXYGEN_DOT_IMAGE_FORMAT svg)
+ set(DOXYGEN_HTML_FILE_EXTENSION .xhtml)
+ set(DOXYGEN_INTERACTIVE_SVG YES)
+ set(DOXYGEN_DOT_MULTI_TARGETS YES)
doxygen_add_docs(
doxygen
${CMAKE_CURRENT_SOURCE_DIR})
@@ -31,16 +42,6 @@ endif()
add_subdirectory(front)
add_subdirectory(back)
-ExternalProject_Add(PolyLib
- GIT_REPOSITORY git@github.com:vincentloechner/polylib.git
- PATCH_COMMAND <SOURCE_DIR>/autogen.sh
- CONFIGURE_COMMAND <SOURCE_DIR>/configure --with-libgmp
- BUILD_IN_SOURCE true
- BUILD_COMMAND make -j
- TEST_COMMAND make tests -j
- INSTALL_COMMAND ""
- EXCLUDE_FROM_ALL true)
-
# Build target
add_executable(pll main.cpp)
target_link_libraries(pll pll_front pll_back)
diff --git a/README.md b/README.md
index 9e94b4a..c084b39 100644
--- a/README.md
+++ b/README.md
@@ -1,4 +1,4 @@
# PolyLingual
PolyLingual is a work in progress on a programmable polyhedral scheduler. The aim is to be able to script a polyhedral scheduling algorithm, and to automatically generate a compilable codebase applying this algorithm.
-[Technical documentation is available here.](https://emilienbauer.pages.unistra.fr/polylingual)
+[Technical documentation is available here.](https://emilienbauer.pages.unistra.fr/polylingual/index.xhtml)
diff --git a/back/periscop/helpers/farkas.c b/back/periscop/helpers/farkas.c
index aea43a6..74d0eb7 100644
--- a/back/periscop/helpers/farkas.c
+++ b/back/periscop/helpers/farkas.c
@@ -202,6 +202,7 @@ Matrix* Farkas_on_delay_dependency(const struct osl_dependence* const D, Value m
n = 1;
m_i = malloc(sizeof(size_t));
m_i[0] = 2;
+
subsp_ij = malloc(sizeof(dep_subspace*));
subsp_ij[0] = malloc(2 * sizeof(dep_subspace));
subsp_ij[0][0] = SRC_IT | PARAMS;
diff --git a/back/periscop/helpers/farkas.h b/back/periscop/helpers/farkas.h
index 4dbcb6e..f012de9 100644
--- a/back/periscop/helpers/farkas.h
+++ b/back/periscop/helpers/farkas.h
@@ -20,38 +20,68 @@ This file is part of PolyLingual.
#ifndef FARKAS_H
#define FARKAS_H
+//! \addtogroup back
+//! @{
+//! \addtogroup periscop
+//! @{
+//! \addtogroup periscop_helpers
+//! @{
+//!
+//! \file
+//! \brief This file defines interfaces for functions related to the Farka's Lemma application
+//!
+//! @}
+//! @}
+//! @}
+
+
#include "osl_to_polylib.h"
#include "utils.h"
#include <polylib/polylibgmp.h>
#include <osl/osl.h>
-//Apply Farkas' Lemma and return the obtained constraints
-// n : number of forms
-//m_i : the number of applications to compose with f_i
-//f_i : the arities of the n forms
-//g_ij : the applications to compose with the f_is. A NULL means no composition(or identity)
-//a_ij : the coefficients
-//b : must be over b
-//D : the polyhedron
-//brief : return the constraints on the f_is for \sum_ij a_ij*f_i(g_ij) to be superior to b over D
+//! \brief Apply Farkas' Lemma and return the obtained constraints
+//! \param n the number \f$ n \f$ of forms
+//! \param m_i the number \f$ m_i \f$ of applications to compose with \f$ f_i \f$
+//! \param f_i the arities \f$ f_i \f$ of the \f$ n \f$ forms
+//! \param g_ij the applications \f$ g_{i,j} \f$ to compose with the \f$ f_is \f$. A NULL means no composition (or identity)
+//! \param a_ij the coefficients \f$ a_{i,j} \f$
+//! \param b the sum must be greater than \f$ b \f$
+//! \param D the polyhedron \f$ D \f$
+//! \return the constraints on all \f$ f_i \f$ such that \f$ \sum\limits_{i,j} a_{i,j} \cdot f_i(g_{i,j}) \f$ is greater than \f$ b \f$ over \f$ D \f$.
+//! \warning You probably won't need to use this form of the function. It is exposed for completeness' sake, but there are specialized forms more suitable for scheduling:
+//! \see Farkas_on_dependency
+//! \see Farkas_on_delay_dependency
Matrix* Farkas(size_t n, size_t* m_i, size_t* f_i, Matrix*** g_ij, Value** a_ij, Value b, Matrix* D);
-//Values to be used in a bitfield to indicate which semantic subspaces of a dependency polyhedron a form is defined on
+//! \brief Enum representing subspaces of a dependency polyhedron's space
+//!
+//! Values to be used in a bitfield to indicate which semantic subspaces of a dependency polyhedron a form is defined on
enum DEPSS{
- SRC_IT = 1,
- SRC_AC = 2,
- TGT_IT = 4,
- TGT_AC = 8,
- PARAMS = 16,
- ALL_SS = PARAMS*2-1,
+ SRC_IT = 1, //!< The source iteration domain
+ SRC_AC = 2, //!< The source access relation
+ TGT_IT = 4, //!< The target iteration domain
+ TGT_AC = 8, //!< The target access relation
+ PARAMS = 16, //!< The parameter space
+ ALL_SS = PARAMS*2-1, //!< The whole dependency space (including paramter space)
};
-//Typedef for the bitfield, syntactic sugar
+//! Typedef for the bitfield, syntactic sugar
typedef ushort dep_subspace ;
+//! \brief The projection matrix from a dependency's space to the passed subspace
+//! \param D The dependence relation
+//! \param subsp The semantic subspace.
+//! \return A projection Matrix suitable to use in composition with a form defined on this subspace.
+//! \see DEPSS
+//! \see Farkas
Matrix* Dependency_subspace_matrix(const struct osl_dependence* const D, dep_subspace subsp);
-//Return the given semantic subspace's dimension for a given dependecy
+//! \brief The actual dimension of a dependency's subspace
+//! \param D The dependence relation
+//! \param subsp The semantic subspace
+//! \return The subspace's actual dimension
+//! \see DEPSS
static inline size_t Dependency_subspace_dim(const struct osl_dependence* const D, dep_subspace subsp)
{
size_t arity = 0;
@@ -64,23 +94,26 @@ static inline size_t Dependency_subspace_dim(const struct osl_dependence* const
return arity;
}
-//Simply return the projection matrix suitable for an affine form define on a semantic
-//subspace of a dependence polyhedron.
-//Helper function for Farkas_on_dependency
-
-//Specialized call for application on a dependency polyhedron : don't bother with the gs and arities.
-//n : number of forms
-//m_i : the number of compositions with f_i
-//subsp_ij : which subspaces the ij composition is defined on
-//a_ij : the coefficients
-//b : must be over b
-//D : the dependence
-//brief : return the constraints on the f_is for their weighted sum to be superior to b over D
+//! \brief Apply Farka's Lemma in the case of a dependency polyhedron
+//!
+//! This is a specialized specialized call for the lemma's application on a dependency polyhedron : the caller doesn't have to think about actual arities or dimensionalities. The caller only specifies on which semantic subspaces each form is defined on.
+//! \param n The number \f$ n \f$ of forms
+//! \param m_i The number \f$ m_i \f$ of compositions with \f$ f_i \f$, or the number of different subspaces \f$ f_i \f$ is defined on.
+//! \param subsp_ij Which subspace the \f$ i,j \f$ composition is defined on. Here we note this composition \f$ f_i(g_{i,j}) \f$, but it can be read as: \f$ f_i \f$ restricted to the subspace \f$ subsp_{i,j}\f$.
+//! \param a_ij The coefficients \f$ a_{i,j} \f$
+//! \param b The combination must be greater than \f$ b\f$ over \f$ D \f$
+//! \param D The dependence \f$ D \f$
+//! \return The constraints on \f$ f_i \f$ such that \f$ \sum\limits_{i,j} a_{i,j} \cdot f_i(g_{i,j}) \f$ is greater than \f$ b \f$ over \f$ D \f$
Matrix* Farkas_on_dependency(size_t n, size_t* m_i, dep_subspace** subsp_ij, Value** a_ij, Value b, const struct osl_dependence* const D);
-//Helper func
+//! \brief Apply Farka's Lemma for a schedule to have a delay greater than some value on some dependency.
+//!
+//! This is a specialized function for the application of the Farka's Lemma. It allows to easily enforce some delay over some dependence for a scheduling, which should be done in nearly every scheduling algorithm, to at least enforce legality.
+//! \param D The dependence relation \f$ D \f$
+//! \param min_delay The minimum delay the template scheduling has to enforce over this dependence.
+//! \return The constraints on the scheduling for it to honor such a delay over \f$ D \f$.
Matrix* Farkas_on_delay_dependency(const struct osl_dependence* const D, Value min_delay);
#endif // FARKAS_H
diff --git a/back/periscop/helpers/osl_to_polylib.h b/back/periscop/helpers/osl_to_polylib.h
index cfa0072..fc49c95 100644
--- a/back/periscop/helpers/osl_to_polylib.h
+++ b/back/periscop/helpers/osl_to_polylib.h
@@ -20,6 +20,20 @@ This file is part of PolyLingual.
#ifndef OSL_TO_POLYLIB_H
#define OSL_TO_POLYLIB_H
+//! \addtogroup back
+//! @{
+//! \addtogroup periscop
+//! @{
+//! \addtogroup periscop_helpers
+//! @{
+//!
+//! \file
+//! \brief This file defines simple function to translate some OpenScop objects to PolyLib objects
+//!
+//! @}
+//! @}
+//! @}
+
#include "limits.h"
#include <osl/scop.h>
@@ -28,13 +42,22 @@ This file is part of PolyLingual.
#include <polylib/polylibgmp.h>
#include <polylib/arithmetique.h>
-extern
-PipOptions_gmp *pip_options;
-
+//! \brief Create a PolyLib Matrix respresenting a convex OpenScop osl_relation
+//! \param relation The relation to translate
+//! \return A Matrix matching the original relation's matrix, in PolyLib format.
+//! \attention All information other than the matrix' coefficients isn't embedded in this Matrix !
Matrix* osl_relation_to_Matrix(const osl_relation_p const relation);
+//! \brief Create a PolyLib Polyhedron representing a convex OpenScop osl_relation
+//! \param relation The relation to translate
+//! \return A Polyhedron matching the original relation's matrix, in PolyLib format.
+//! \attention All information other than the matrix' coefficients isn't embedded in this Polyhedron !
Polyhedron* osl_relation_to_Polyhedron(const osl_relation_p const relation);
+//! \brief Create a PolyLib Domain representing an OpenScop osl_relation
+//! \param relation The relation to translate
+//! \return A Polyhedral domain matching the original relation's matrix, in PolyLib format.
+//! \attention All information other than the matrices' coefficients isn't embedded in this Polyhedral domain !
Polyhedron* osl_relation_to_Domain(osl_relation_p relation);
#endif
diff --git a/back/periscop/helpers/utils.h b/back/periscop/helpers/utils.h
index 835f15f..ab3787f 100644
--- a/back/periscop/helpers/utils.h
+++ b/back/periscop/helpers/utils.h
@@ -20,24 +20,71 @@ This file is part of PolyLingual.
#ifndef UTILS_H
#define UTILS_H
+//! \addtogroup back
+//! @{
+//! \addtogroup periscop
+//! @{
+//! \addtogroup periscop_helpers
+//! @{
+//!
+//! \file
+//! \brief This file defines various utilities used to implement a polyhedral scheduler with periscop and PolyLib
+//!
+//! @}
+//! @}
+//! @}
+
#include <polylib/polylibgmp.h>
#include <osl/osl.h>
#include <piplib/piplib_gmp.h>
+//! \brief The user-defined verbosity level
extern int verbose;
-enum output {MATRIX, OPENSCOP, CODE};
+//! \brief simple enum for the scheduler's output format
+enum output {
+ MATRIX, //!< Simply print the scheduling as a Matrix
+ OPENSCOP, //!< Clone and modify the original SCoP to match the scheduling
+ CODE //!< Use CLooG to directly output the corresponding source code
+};
+//! \brief Eliminate variables from a constraint system
+//!
+//! Eliminate variables from a constraints system, keeping the variables indices as passed. This is done using PolyLib's double respresentation.
+//! \param sys The constraints system
+//! \param f The first variable index to keep
+//! \param t The last variable index to keep
+//! \return The constraints on the keeped variables obtained after elimination
Matrix* project_system_from_to(Matrix *sys, unsigned f, unsigned t);
+//! \brief Simplify the dependencies set **in place**
+//!
+//! Eliminates **in place** all dependencies appearing twice, that is, the same dependency relation for a different dependence type. This may not always be desired !
+//! \param dependencies The dependencies list to simplify
void simplify_dependencies(struct osl_dependence * const dependencies);
+//! \brief Cast a **non-parameterized** PipQuest to a PolyLib Vector
+//!
+//! Cast a **non-parameterized** PipQuest to a PolyLib Vector. PipQuast are trees, where each node may have arbitrarily many children, which correspond to different values of some parameter.
+//! This is to be used in the non-parameterized case, where this PipQuast then is always a list.
+//!
+//! \param quast The PipQuast to cast
+//! \param from The first value index to include in the Vector
+//! \param n The number of values to include in the Vector
+//! \return The Vector containing the n values starting from from.
Vector* PipQuast_to_Vector(PipQuast_gmp* quast, unsigned from, unsigned n);
+//! \brief Return a new dependencies list corresponding to a passed selection.
+//!
+//! \param dependencies The original list to copy and filter
+//! \param selected A Vector, which should be of the same length than the list, and where a 0 means discard and 1 means keep, the corresponding dependency.
+//! \return A list of **copies** of the selected dependencies.
osl_dependence_p remove_scheduled_dependencies(osl_dependence_p dependencies, Vector* selected);
-void positive_scattering_coefficients(osl_scop_p scop);
-
+//! \brief Apply **in-place** a new scheduling to a SCoP
+//!
+//! \param scop The SCoP to set a new scheduling on
+//! \param schedule The Matrix corresponding to the new schedule
void apply_schedule_to_scop(osl_scop_p scop, Matrix* schedule);
#endif //UTILS_H
diff --git a/doxygen.h b/doxygen.h
new file mode 100644
index 0000000..de23812
--- /dev/null
+++ b/doxygen.h
@@ -0,0 +1,13 @@
+//! \defgroup front Front end
+//! \brief The module containing all parsing and AST logic.
+
+//! \defgroup back Back end
+//! \brief The module grouping the different target PolyLingual can generate code to.
+
+//! \defgroup periscop Periscop+PolyLib
+//! \brief The module for the Periscop+PolyLib target.
+
+//! \defgroup periscop_helpers Helpers
+//! \brief The module containing various utilities for the Periscop+PolyLib target.
+//!
+//! This is meant to be compiled as a library, which should be linked against the generated scheduler code. This is supposed to avoid recompiling those utilites everytime a scheduler is compiled.
diff --git a/front/ast.cpp b/front/ast.cpp
index 395f495..6cfb100 100644
--- a/front/ast.cpp
+++ b/front/ast.cpp
@@ -31,8 +31,10 @@ Integer::Integer(const std::string& text) : Integer(std::stoi(text))
{}
Integer& Integer::operator =(const Integer& other){ value = other.value; return *this;}
+
std::ostream& operator <<(std::ostream& os, const Integer& integer)
{ return os << integer.value; }
+
std::istream& operator >>(std::istream& is, Integer& integer)
{ return is >> integer.value; }
diff --git a/front/ast.hpp b/front/ast.hpp
index fd61101..2dfcfa0 100644
--- a/front/ast.hpp
+++ b/front/ast.hpp
@@ -26,39 +26,73 @@ This file is part of PolyLingual.
namespace pll {
+//! \addtogroup front
+//! @{
+//!
+//! \file Defines various AST nodes
+//!
+//! @}
+//! @}
+
+//! \brief Abstract base class for any node in the AST
+//! \ingroup front
class Node
{
public:
virtual ~Node() = default;
};
+//! \brief Abstract base class for any statement in the AST
+//! \ingroup front
class Statement : public Node
{
};
+//! \brief Abstract base class for any expression in the AST
+//! \ingroup front
class Expression : public Node
{
};
+//! \brief Represents a litteral integer
+//! \ingroup front
class Integer : public Expression
{
public:
+ //! \brief Construct a new Integer from an int value
+ //! \param value int-encoded value to build the Integer with
Integer(int value = 0);
+ //! \brief Construct a new Integer from another one
Integer(const Integer& other);
+ //! \brief Construct a new Integer from text to parse
Integer(const std::string& text);
+ //! \brief Assignment operator from another Integer
Integer& operator =(const Integer& other);
private:
int value;
+ //! \brief Stream output operator
+ //!
+ //! Prints the Integer's value on the stream
+ //! \param os The ostream to print to
+ //! \param integer The Integer to print the value of
friend std::ostream& operator <<(std::ostream& os, const Integer& integer);
+
+ //! \brief Stream input operator.
+ //!
+ //! Parse the Integer's new value from the stream
+ //! \param is The istream to read from
+ //! \param integer The Integer to parse the value of
+ //! \return The stream with the integer's value's text consumed
friend std::istream& operator >>(std::istream& is, Integer& integer);
};
+//! \brief Simple typedef for an AST, which is a pointer to its root
+//! \ingroup front
using AST = std::unique_ptr<Node>;
}
-
#endif // NODE_H
--
GitLab