Commit 2c927865 authored by Swann Perarnau's avatar Swann Perarnau
Browse files

[doc] convert documentation to sphinx+breathe

Also create the basic page structure, including importing the doxygen
API documentation through breathe.

Also fix some doxygen config, as doxygen wasn't generating scratchpad
info, and the dma implementation groups had a different name that the
structs.
parent 669a4f7e
......@@ -794,8 +794,8 @@ INPUT = ../include \
../include/aml/area \
../include/aml/tiling \
../include/aml/dma \
../include/aml/scratch \
../include/aml/utils \
md \
../CONTRIBUTING.markdown
img/building-blocks-diagram.png
......@@ -1953,7 +1953,7 @@ MAN_LINKS = NO
# captures the structure of the code including all documentation.
# The default value is: NO.
GENERATE_XML = NO
GENERATE_XML = YES
# The XML_OUTPUT tag is used to specify where the XML pages will be put. If a
# relative path is entered the value of OUTPUT_DIRECTORY will be put in front of
......
......@@ -24,8 +24,10 @@ import os
import sys
import subprocess
# Generate documentation
subprocess.call('doxygen aml.doxy', shell=True)
# Generate doxygen first if in read the docs.
read_the_docs = os.environ.get('READTHEDOCS', None) == 'True'
if read_the_docs:
subprocess.call('doxygen aml.doxy', shell=True)
# -- General configuration ---------------------------------------------------
......@@ -35,7 +37,7 @@ language = 'C'
# Add any Sphinx extension module names here, as strings. They can be
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
# ones.
extensions = []
extensions = ["breathe", "recommonmark"]
# Add any paths that contain templates here, relative to this directory.
templates_path = []
......@@ -45,25 +47,32 @@ templates_path = []
# This pattern also affects html_static_path and html_extra_path.
exclude_patterns = []
# ensure that the master file is index.
# mostly needed because the sphinx version on RTD expects a contents.rst
# instead.
master_doc = 'index'
# -- Project information -----------------------------------------------------
project = 'AML'
copyright = 'Copyright 2019 UChicago Argonne, LLC'
author = 'Swann Perarnau, Kamil Iskra, Brian Suchy, Valentin Reis, Nicolas Denoyelle'
release = 'X.X.X'
release = '0.1.0'
# -- Options for HTML output -------------------------------------------------
# The theme to use for HTML and HTML Help pages. See the documentation for
# a list of builtin themes.
#
html_theme = 'alabaster'
if read_the_docs:
html_theme = 'default'
else:
html_theme = "sphinx_rtd_theme"
# Add any paths that contain custom static files (such as style sheets) here,
# relative to this directory. They are copied after the builtin static files,
# so a file named "default.css" will overwrite the builtin "default.css".
html_static_path = []
#Overwrite sphinx documentation with doxygen documentation.
html_extra_path = ['build-doxygen/html']
breathe_projects = {"aml": "build-doxygen/xml"}
breathe_default_project = "aml"
This is an empty file required by shpinx when
compiling documentation on readthedocs.org.
This is an empty landing page overwritten with doxygen documentation.
AML: Building Blocks for Explicit Memory Management
===================================================
AML is a memory management library designed to ease the use of complex memory
topologies and complex data layout optimizations for high-performance computing
applications.
AML is Open Source, distributed under the BSD 3 clause license.
Overview
--------
AML is a framework providing locality-preserving abstractions to application
developers. In particular, AML aims to expose flexible interfaces to describe
and reason about how applications deal with data layout, tiling of data,
placement of data across hardware topologies, and affinity between work and
data.
AML is organized as a collection of abstractions, presented as *building
blocks*, to develop explicit memory and data management policies. AML goals
are:
* **composability**: application developers and performance experts should be
to pick and choose which building blocks to use depending on their specific
needs.
* **flexibility**: users should be able to customize, replace, or change the
configuration of each building block as much as possible.
As of now, AML implements the following abstractions:
.. image:: img/building-blocks-diagram.png
:width: 300px
:align: right
* :doc:`Areas <pages/areas>`, a set of addressable physical memories,
* :doc:`Tilings <pages/tilings>`, a description of tiling data structures,
* :doc:`DMAs <pages/dmas>`, an engine to asynchronously move data structures between areas,
* :doc:`Scratchpads <pages/scratchs>`, a stage-in, stage-out abstraction for prefetching.
Each of these abstractions have several implementations. For instance, areas
may refer to usual DRAM or a subset of them, GPU memory or non-volatile memory.
Tilings are implemented to reflect either 1D or 2D structures and so on.
Quick Start Guide
-----------------
Download
~~~~~~~~
* `Development version <https://xgitlab.cels.anl.gov/argo/aml>`_:
.. code-block:: console
$ git clone git@xgitlab.cels.anl.gov:argo/aml.git
Requirements:
~~~~~~~~~~~~~
* autoconf
* automake
* libtool
* libnuma
Installation
~~~~~~~~~~~~
.. code-block:: console
$ sh autogen.sh
$ ./configure
$ make -j install
Workflow
~~~~~~~~
Include aml header:
.. code-block:: c
#include <aml.h>
...
int main(int argc, char **argv){
Check AML version:
.. code-block:: c
if(aml_version_major != AML_VERSION_MAJOR){
printf("AML ABI mismatch!");
return 1;
}
Initialize and Cleanup AML:
.. code-block:: c
if(aml_init(&argc, &argv) != 0){
printf("AML library init failure!");
return 1;
}
...
aml_finalize();
Link your program with *-laml*.
See above building blocks specific pages for further examples and information
on library features.
Support
-------
Support for AML is provided through the
`gitlab issue interface <https://xgitlab.cels.anl.gov/argo/aml/issues>`_.
Alternatively you can contact directly the developers/maintainers:
* Swann Perarnau (swann AT anl DOT gov)
* Nicolas Denoyelle (ndenoyelle AT anl DOT gov)
Contributing
------------
AML welcomes any comment, suggestion, bug reporting, or feature request, as
well as code contributions. See the [contributing page](@ref contributing_page)
for more info.
.. toctree::
:maxdepth: 2
pages/areas
pages/tilings
pages/dmas
pages/scratchs
Welcome to AML Documentation Page {#index}
============
AML is a memory management library designed to ease the use of complex memory
topologies and complex data layout optimizations for high-performance computing
applications.
AML is Open Source, distributed under the BSD 3 clause license.
## Overview
AML is a framework providing locality-preserving abstractions to application
developers. In particular, AML aims to expose flexible interfaces to describe
and reason about how applications deal with data layout, tiling of data,
placement of data across hardware topologies, and affinity between work and
data.
AML is organized as a collection of abstractions, presented as *building
blocks*, to develop explicit memory and data management policies. AML goals
are:
* __composability__: application developers and performance experts should be
to pick and choose which building blocks to use depending on their specific
needs.
* __flexibility__: users should be able to customize, replace, or change the
configuration of each building block as much as possible.
As of now, AML implements the following abstractions:
\image html building-blocks-diagram.png width=400cm
* [Areas](@ref aml_area), a set of addressable physical memories,
* [Tilings](@ref aml_tiling), a description of tiling data structures,
* [DMA](@ref aml_dma), an engine to asynchronously move data structures between areas,
* [Scratchpad](@ref aml_scratch), a stage-in, stage-out abstraction for prefetching.
Each of these abstractions have several implementations. For instance, areas
may refer to usual DRAM or a subset of them, GPU memory or non-volatile memory.
Tilings are implemented to reflect either 1D or 2D structures and so on.
## Quick Start Guide
### Download
* [Development version](https://xgitlab.cels.anl.gov/argo/aml):
```
git clone git@xgitlab.cels.anl.gov:argo/aml.git
```
* Release versions:
TODO after release.
### Requirements:
* autoconf
* automake
* libtool
* libnuma
### Installation
```
sh autogen.sh
./configure
make -j install
```
### Workflow
* Include aml header:
```
#include <aml.h>
...
int main(int argc, char **argv){
```
* Check AML version:
```
if(aml_version_major != AML_VERSION_MAJOR){
printf("AML ABI mismatch!");
return 1;
}
```
* Initialize and Cleanup AML:
```
if(aml_init(&argc, &argv) != 0){
printf("AML library init failure!");
return 1;
}
...
aml_finalize();
```
* Link your program with `-laml`
See above building blocks specific pages for further examples and information
on library features.
## Support
Support for AML is provided through the
[gitlab issue interface](https://xgitlab.cels.anl.gov/argo/aml/issues).
Alternatively you can contact directly the developers/maintainers:
* Swann Perarnau (swann AT anl DOT gov)
* Nicolas Denoyelle (ndenoyelle AT anl DOT gov)
## Contributing
AML welcomes any comment, suggestion, bug reporting, or feature request, as
well as code contributions. See the [contributing page](@ref contributing_page)
for more info.
Area Linux Implementation API
=================================
.. doxygengroup:: aml_area_linux
Areas: Addressable Physical Memories
====================================
.. doxygengroup:: aml_area
Implementations
---------------
.. toctree::
area_linux_api
DMA Linux Parallel Implementation API
=====================================
.. doxygengroup:: aml_dma_linux_par
DMA Linux Sequential Implementation API
=======================================
.. doxygengroup:: aml_dma_linux_seq
DMAs: Moving Data Across Areas
====================================
.. doxygengroup:: aml_dma
Implementations
---------------
.. toctree::
dma_linux_seq_api
dma_linux_par_api
Scratchpad Parallel Implementation API
======================================
.. doxygengroup:: aml_scratch_par
Scratchpad Sequential Implementation API
========================================
.. doxygengroup:: aml_scratch_seq
Scratchpads: Staging in and out data
====================================
.. doxygengroup:: aml_scratch
Implementations
---------------
.. toctree::
scratch_seq_api
scratch_par_api
Tiling 1D Implementation API
============================
.. doxygengroup:: aml_tiling_1d
Tiling 2D Implementation API
============================
.. doxygengroup:: aml_tiling_2d
Tilings: Decomposing Data
====================================
.. doxygengroup:: aml_tiling
Implementations
---------------
.. toctree::
tiling_1d_api
tiling_2d_api
......@@ -12,7 +12,7 @@
#define AML_DMA_LINUX_PAR_H 1
/**
* @defgroup aml_dma_par "AML Parallel DMA"
* @defgroup aml_dma_linux_par "AML Parallel DMA"
* @brief Parallel DMA implementation.
*
* DMA logic implemented based on general linux API, asynchronous execution
......
......@@ -12,7 +12,7 @@
#define AML_DMA_LINUX_SEQ_H 1
/**
* @defgroup aml_dma_seq "AML Sequential DMA"
* @defgroup aml_dma_linux_seq "AML Sequential DMA"
* @brief Sequential DMA implementation.
*
* DMA logic implemented based on general linux API, with the caller thread
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment