Lerking/OSACA
1
0
Fork 0
mirror of https://github.com/RRZE-HPC/OSACA.git synced 2025-12-15 16:40:05 +01:00
Code Issues Packages Projects Releases Wiki Activity

added Sphinx documentation for RTD

Browse Source
This commit is contained in:
JanLJL
2020-03-05 16:44:18 +01:00
parent c194f57f09
commit 5fc660484c
13 changed files with 664 additions and 12 deletions
Download Patch File Download Diff File Expand all files Collapse all files

24
README.rst
View File

@@ -1,4 +1,4 @@
.. image:: doc/osaca-logo.png
.. image:: doc/img/osaca-logo.png
:alt: OSACA logo
:width: 80%
@@ -44,16 +44,16 @@ Dependencies:
-------------
Additional requirements are:
- `Python3 <https://www.python.org/>`_
- `Graphviz <https://www.graphviz.org/>`_ for dependency graph creation (minimal dependency is `libgraphviz-dev` on Ubuntu)
- `Kerncraft <https://github.com/RRZE-HPC/kerncraft>`_ >=v0.8.4 for marker insertion
- `ibench <https://github.com/RRZE-HPC/ibench>`_ or `asmbench <https://github.com/RRZE-HPC/asmbench/>`_ for throughput/latency measurements
- `Python3 <https://www.python.org/>`__
- `Graphviz <https://www.graphviz.org/>`__ for dependency graph creation (minimal dependency is `libgraphviz-dev` on Ubuntu)
- `Kerncraft <https://github.com/RRZE-HPC/kerncraft>`__ >=v0.8.4 for marker insertion
- `ibench <https://github.com/RRZE-HPC/ibench>`__ or `asmbench <https://github.com/RRZE-HPC/asmbench/>`__ for throughput/latency measurements
Design
======
A schematic design of OSACA's workflow is shown below:
.. image:: doc/osaca-workflow.png
.. image:: doc/img/osaca-workflow.png
:alt: OSACA workflow
:width: 80%
@@ -88,10 +88,10 @@ The usage of OSACA can be listed as:
Import a given microbenchmark output file into the corresponding architecture instruction database.
Define the type of microbenchmark either as "ibench" or "asmbench".
--insert-marker
OSACA calls the Kerncraft module for the interactively insertion of `IACA <https://software.intel.com/en-us/articles/intel-architecture-code-analyzer>`_ byte markers or OSACA AArch64 byte markers in suggested assembly blocks.
OSACA calls the Kerncraft module for the interactively insertion of `IACA <https://software.intel.com/en-us/articles/intel-architecture-code-analyzer>`__ byte markers or OSACA AArch64 byte markers in suggested assembly blocks.
--export-graph EXPORT_PATH
Output path for .dot file export. If "." is given, the file will be stored as "./osaca_dg.dot".
After the file was created, you can convert it to a PDF file using `dot <https://graphviz.gitlab.io/_pages/pdf/dotguide.pdf>`_.
After the file was created, you can convert it to a PDF file using `dot <https://graphviz.gitlab.io/_pages/pdf/dotguide.pdf>`__.
--ignore-unknown
Force OSACA to apply a throughput and latency of 0.0 cy for all unknown instruction forms.
If not specified, a warning will be printed instead if one ore more isntruction form is unknown to OSACA.
@@ -128,7 +128,7 @@ To get a visualization of the analyzed kernel and its dependency chains, OSACA p
The tool highlights all LCDs and the CP.
The graph generation is done by running OSACA with the ``--export-graph EXPORT_GRAPH`` flag.
OSACA stores the DOT file either at the by ``EXPORT_GRAPH`` specified filepath or uses the default filename "osaca_dg.dot" in the current working directory.
Subsequently, the DOT-graph can be adjusted in its appearance and converted to various output formats such as PDF, SVG, or PNG using the `dot command <https://graphviz.gitlab.io/_pages/pdf/dotguide.pdf>`_, e.g., ``dot -Tpdf osaca_dg.dot -o
Subsequently, the DOT-graph can be adjusted in its appearance and converted to various output formats such as PDF, SVG, or PNG using the `dot command <https://graphviz.gitlab.io/_pages/pdf/dotguide.pdf>`__, e.g., ``dot -Tpdf osaca_dg.dot -o
graph.pdf`` to generate a PDF document.
Marker insertion
@@ -196,7 +196,7 @@ This can be done by using the ``--insert-marker`` flag together with the path to
Benchmark import
----------------
OSACA supports the automatic integration of new instruction forms by parsing the output of the micro-
benchmark tools `asmbench <https://github.com/RRZE-HPC/asmbench>`_ and `ibench <https://github.com/RRZE-HPC/ibench>`_.
benchmark tools `asmbench <https://github.com/RRZE-HPC/asmbench>`__ and `ibench <https://github.com/RRZE-HPC/ibench>`__.
This can be achieved by running OSACA with the command line option ``--import MICROBENCH``:
.. code-block:: bash
@@ -337,7 +337,7 @@ It shows the whole kernel together with the optimized port pressure of each inst
Furthermore, in the two columns on the right, the critical path (CP) and the longest loop-carried dependency (LCD) of the loop kernel.
In the bottom, all loop-carried dependencies are shown, each with a list of line numbers being part of this dependency chain on the right.
You can find more (already marked) examples and sample outputs for various architectures in the `examples <examples/>`_ directory.
You can find more (already marked) examples and sample outputs for various architectures in the `examples <examples/>`__ directory.
Credits
=======
@@ -345,7 +345,7 @@ Implementation: Jan Laukemann
License
=======
`AGPL-3.0 </LICENSE>`_
`AGPL-3.0 </LICENSE>`__
.. # define a hard line break for HTML
.. |br| raw:: html