From a4df17a31f0baf52a48f0a6d43af509a621957e3 Mon Sep 17 00:00:00 2001 From: Philipp van Kempen Date: Fri, 26 Apr 2024 14:33:23 +0200 Subject: [PATCH 01/30] add initial sphinx doc infrastructure (#16) --- docs/.gitignore | 1 + docs/Makefile | 20 +++++ docs/_static/.gitkeep | 0 docs/conf.py | 169 ++++++++++++++++++++++++++++++++++++++++++ docs/index.rst | 14 ++++ docs/readme.rst | 2 + docs/requirements.txt | 6 ++ 7 files changed, 212 insertions(+) create mode 100644 docs/.gitignore create mode 100644 docs/Makefile create mode 100644 docs/_static/.gitkeep create mode 100644 docs/conf.py create mode 100644 docs/index.rst create mode 100644 docs/readme.rst create mode 100644 docs/requirements.txt diff --git a/docs/.gitignore b/docs/.gitignore new file mode 100644 index 00000000..e35d8850 --- /dev/null +++ b/docs/.gitignore @@ -0,0 +1 @@ +_build diff --git a/docs/Makefile b/docs/Makefile new file mode 100644 index 00000000..b3440811 --- /dev/null +++ b/docs/Makefile @@ -0,0 +1,20 @@ +# Minimal makefile for Sphinx documentation +# + +# You can set these variables from the command line. +SPHINXOPTS = +SPHINXBUILD = python -msphinx +SPHINXPROJ = mlonmcu +SOURCEDIR = . +BUILDDIR = _build + +# Put it first so that "make" without argument is like "make help". +help: + @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) + +.PHONY: help Makefile + +# Catch-all target: route all unknown targets to Sphinx using the new +# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). +%: Makefile + @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) diff --git a/docs/_static/.gitkeep b/docs/_static/.gitkeep new file mode 100644 index 00000000..e69de29b diff --git a/docs/conf.py b/docs/conf.py new file mode 100644 index 00000000..d3e9fe30 --- /dev/null +++ b/docs/conf.py @@ -0,0 +1,169 @@ +#!/usr/bin/env python +# +# Copyright (c) 2024 TUM Department of Electrical and Computer Engineering. +# +# This file is part of Seal5. +# See https://github.com/tum-ei-eda/seal5.git for further info. +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. +# + +# If extensions (or modules to document with autodoc) are in another +# directory, add these directories to sys.path here. If the directory is +# relative to the documentation root, use os.path.abspath to make it +# absolute, like shown here. +# +import os +import sys + +sys.path.insert(0, os.path.abspath("..")) + +# pylint: disable=wrong-import-position +import seal5.version # noqa: E402 + +# -- General configuration --------------------------------------------- + +# If your documentation needs a minimal Sphinx version, state it here. +# +# needs_sphinx = '1.0' + +# Add any Sphinx extension module names here, as strings. They can be +# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom ones. +extensions = ["sphinx.ext.autodoc", "sphinx.ext.viewcode", "myst_parser", "numpydoc", "sphinxemoji.sphinxemoji"] +numpydoc_show_class_members = False + +# Add any paths that contain templates here, relative to this directory. +templates_path = ["_templates"] + +# The suffix(es) of source filenames. +# You can specify multiple suffix as a list of string: +# +# source_suffix = ['.rst', '.md'] +source_suffix = ".rst" + +# The master toctree document. +master_doc = "index" + +# General information about the project. +project = "ML on MCU" +copyright = "2021, TUM Department of Electrical and Computer Engineering - Chair of Electronic Design Automation" +author = "TUM Department of Electrical and Computer Engineering - Chair of Electronic Design Automation" + +# The version info for the project you're documenting, acts as replacement +# for |version| and |release|, also used in various other places throughout +# the built documents. +# +# The short X.Y version. +version = seal5.version.__version__ +# The full version, including alpha/beta/rc tags. +release = seal5.version.__version__ + +# The language for content autogenerated by Sphinx. Refer to documentation +# for a list of supported languages. +# +# This is also used if you do content translation via gettext catalogs. +# Usually you set "language" from the command line for these cases. +language = "en" + +# List of patterns, relative to source directory, that match files and +# directories to ignore when looking for source files. +# This patterns also effect to html_static_path and html_extra_path +exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"] + +# The name of the Pygments (syntax highlighting) style to use. +pygments_style = "sphinx" + +# If true, `todo` and `todoList` produce output, else they produce nothing. +todo_include_todos = False + + +# -- 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' +html_theme = "sphinx_rtd_theme" + +# Theme options are theme-specific and customize the look and feel of a +# theme further. For a list of options available for each theme, see the +# documentation. +# +# html_theme_options = {} + +# 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 = ["_static"] + + +# -- Options for HTMLHelp output --------------------------------------- + +# Output file base name for HTML help builder. +htmlhelp_basename = "seal5doc" + + +# -- Options for LaTeX output ------------------------------------------ + +latex_elements = { + # The paper size ('letterpaper' or 'a4paper'). + # + # 'papersize': 'letterpaper', + # The font size ('10pt', '11pt' or '12pt'). + # + # 'pointsize': '10pt', + # Additional stuff for the LaTeX preamble. + # + # 'preamble': '', + # Latex figure (float) alignment + # + # 'figure_align': 'htbp', +} + +# Grouping the document tree into LaTeX files. List of tuples +# (source start file, target name, title, author, documentclass +# [howto, manual, or own class]). +latex_documents = [ + ( + master_doc, + "seal5.tex", + "Seal5 Documentation", + "TUM Department of Electrical and Computer Engineering - Chair of Electronic Design Automation", + "manual", + ), +] + + +# -- Options for manual page output ------------------------------------ + +# One entry per manual page. List of tuples +# (source start file, name, description, authors, manual section). +man_pages = [(master_doc, "seal5", "Seal5 Documentation", [author], 1)] + + +# -- Options for Texinfo output ---------------------------------------- + +# Grouping the document tree into Texinfo files. List of tuples +# (source start file, target name, title, author, +# dir menu entry, description, category) +texinfo_documents = [ + ( + master_doc, + "seal5", + "Seal5 Documentation", + author, + "seal5", + "One line description of project.", + "Miscellaneous", + ), +] diff --git a/docs/index.rst b/docs/index.rst new file mode 100644 index 00000000..948c9380 --- /dev/null +++ b/docs/index.rst @@ -0,0 +1,14 @@ +Seal5 documentation +=================== + +.. toctree:: + :maxdepth: 2 + :caption: Contents: + + readme + +Indices and tables +================== +* :ref:`genindex` +* :ref:`modindex` +* :ref:`search` diff --git a/docs/readme.rst b/docs/readme.rst new file mode 100644 index 00000000..339dc8f4 --- /dev/null +++ b/docs/readme.rst @@ -0,0 +1,2 @@ +.. include:: ../README.md + :parser: myst_parser.sphinx_ diff --git a/docs/requirements.txt b/docs/requirements.txt new file mode 100644 index 00000000..a8e12d4f --- /dev/null +++ b/docs/requirements.txt @@ -0,0 +1,6 @@ +-r ../requirements_dev.txt +Sphinx>=5.0 +myst-parser +numpydoc +sphinx_rtd_theme +sphinxemoji From 996ebe58fd547b226a8df51296ff9612e85b14b9 Mon Sep 17 00:00:00 2001 From: Philipp van Kempen Date: Fri, 26 Apr 2024 14:39:08 +0200 Subject: [PATCH 02/30] add ci job to build shpinx docs --- .github/workflows/docs.yml | 48 ++++++++++++++++++++++++++++++++++++++ 1 file changed, 48 insertions(+) create mode 100644 .github/workflows/docs.yml diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml new file mode 100644 index 00000000..e7caa281 --- /dev/null +++ b/.github/workflows/docs.yml @@ -0,0 +1,48 @@ +name: Build Documentation + +on: + push: + branches: + - main + tags: + - 'v*' + pull_request: + branches: + - main + workflow_dispatch: + +jobs: + docs: + runs-on: ubuntu-latest + strategy: + matrix: + python-version: [3.10] + steps: + - uses: actions/checkout@v3 + - name: Set up Python ${{ matrix.python-version }} + uses: actions/setup-python@v4 + with: + python-version: ${{ matrix.python-version }} + - name: Initialize Virtualenv + run: | + python -m pip install --upgrade pip virtualenv + python -m venv .venv + - name: Install dependencies + run: | + source .venv/bin/activate + pip install -r requirements.txt + pip install -r docs/requirements.txt + - name: Install package into virtualenv + run: | + source .venv/bin/activate + make install + - name: Build docs + run: | + source .venv/bin/activate + make docs + - name: Deploy docs + uses: peaceiris/actions-gh-pages@v3 + if: ${{ github.ref == 'refs/heads/main' }} + with: + github_token: ${{ secrets.GITHUB_TOKEN }} + publish_dir: ./docs/_build/html From e5447b471f7aee2996b8f4ef3766b17b961880c6 Mon Sep 17 00:00:00 2001 From: Philipp van Kempen Date: Fri, 26 Apr 2024 14:41:48 +0200 Subject: [PATCH 03/30] lint code --- examples/demo.py | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/examples/demo.py b/examples/demo.py index 77040301..a94ec41e 100644 --- a/examples/demo.py +++ b/examples/demo.py @@ -67,8 +67,7 @@ seal5_flow.load(cdsl_files, verbose=VERBOSE, overwrite=True) # Load test inputs -test_files = [ -] +test_files = [] seal5_flow.load(test_files, verbose=VERBOSE, overwrite=True) # Load YAML inputs From 3006bfe557272119abb1cc5578fa6178e2f7b7c0 Mon Sep 17 00:00:00 2001 From: Philipp van Kempen Date: Fri, 26 Apr 2024 14:43:11 +0200 Subject: [PATCH 04/30] lint code --- seal5/flow.py | 9 +++++++-- 1 file changed, 7 insertions(+), 2 deletions(-) diff --git a/seal5/flow.py b/seal5/flow.py index 377ac14c..fbfda4ba 100644 --- a/seal5/flow.py +++ b/seal5/flow.py @@ -163,7 +163,7 @@ def create_passes(self): ("detect_side_effects", passes.detect_side_effects, {}), ("detect_inouts", passes.detect_inouts, {}), ("detect_registers", passes.detect_registers, {}), - ("write_cdsl_full", passes.write_cdsl, {"split": False, "compat": False}) + ("write_cdsl_full", passes.write_cdsl, {"split": False, "compat": False}), # TODO: determine static constraints (xlen,...) -> subtargetvmap # detect memory adressing modes # self.detect_adressing_modes(verbose) # TODO @@ -235,7 +235,12 @@ def initialize( else: if force: self.repo, sha, version_info = llvm.clone_llvm_repo( - self.directory, clone_url, ref=clone_ref, refresh=True, label=self.name, git_settings=self.settings.git + self.directory, + clone_url, + ref=clone_ref, + refresh=True, + label=self.name, + git_settings=self.settings.git, ) if self.settings.meta_dir.is_dir(): if force is False and not utils.ask_user( From 53b8c25a7c9b54894fd7cf3532cb47890ec0710d Mon Sep 17 00:00:00 2001 From: Philipp van Kempen Date: Fri, 26 Apr 2024 14:47:42 +0200 Subject: [PATCH 05/30] fix typo in flake8 config --- setup.cfg | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/setup.cfg b/setup.cfg index 31681296..6567cba8 100644 --- a/setup.cfg +++ b/setup.cfg @@ -17,5 +17,5 @@ disable = duplicate-code,fixme [flake8] max-line-length = 120 -# ingore = E203,W503 -exclude = seal5/frontends/coredsl2_seal5/parser_gen +extend-ignore = E203,W503 +exclude = seal5/frontends/coredsl2_seal5/parser_gen,seal5/resources/ From a27d78696e10b1827c980f4d19aa4e7fb9b4a7c6 Mon Sep 17 00:00:00 2001 From: Philipp van Kempen Date: Fri, 26 Apr 2024 14:50:47 +0200 Subject: [PATCH 06/30] ci: increase python version to v3.10 --- .github/workflows/demo.yml | 2 +- .github/workflows/docs.yml | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/.github/workflows/demo.yml b/.github/workflows/demo.yml index 6ccc2f2a..2867afff 100644 --- a/.github/workflows/demo.yml +++ b/.github/workflows/demo.yml @@ -51,7 +51,7 @@ jobs: runs-on: ubuntu-latest strategy: matrix: - python-version: [3.8] + python-version: ["3.10"] steps: - uses: actions/checkout@v3 with: diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index e7caa281..02f0e7de 100644 --- a/.github/workflows/docs.yml +++ b/.github/workflows/docs.yml @@ -16,7 +16,7 @@ jobs: runs-on: ubuntu-latest strategy: matrix: - python-version: [3.10] + python-version: ["3.10"] steps: - uses: actions/checkout@v3 - name: Set up Python ${{ matrix.python-version }} From c460e5a14b5f23658378bba44f8494166ffbe192 Mon Sep 17 00:00:00 2001 From: Philipp van Kempen Date: Fri, 26 Apr 2024 14:57:29 +0200 Subject: [PATCH 07/30] ci: fix docs jobs --- .github/workflows/docs.yml | 11 +++++++++-- 1 file changed, 9 insertions(+), 2 deletions(-) diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index 02f0e7de..a884fe8d 100644 --- a/.github/workflows/docs.yml +++ b/.github/workflows/docs.yml @@ -35,11 +35,18 @@ jobs: - name: Install package into virtualenv run: | source .venv/bin/activate - make install + pip install -e . - name: Build docs run: | source .venv/bin/activate - make docs + cd docs + make html + - name: Archive environment (without deps) + uses: actions/upload-artifact@v2 + with: + name: html-docs + path: docs/_build/html + if: ${{ github.event.inputs.artifact == 'true' }} - name: Deploy docs uses: peaceiris/actions-gh-pages@v3 if: ${{ github.ref == 'refs/heads/main' }} From 008828fe0c77a4031e0e56be1a2b4720e60d13db Mon Sep 17 00:00:00 2001 From: Philipp van Kempen Date: Fri, 26 Apr 2024 14:59:15 +0200 Subject: [PATCH 08/30] ci: fix docs jobs --- .github/workflows/docs.yml | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index a884fe8d..fff64d7c 100644 --- a/.github/workflows/docs.yml +++ b/.github/workflows/docs.yml @@ -46,10 +46,10 @@ jobs: with: name: html-docs path: docs/_build/html - if: ${{ github.event.inputs.artifact == 'true' }} - - name: Deploy docs - uses: peaceiris/actions-gh-pages@v3 - if: ${{ github.ref == 'refs/heads/main' }} - with: - github_token: ${{ secrets.GITHUB_TOKEN }} - publish_dir: ./docs/_build/html + # TODO: enable after open source release + # - name: Deploy docs + # uses: peaceiris/actions-gh-pages@v3 + # if: ${{ github.ref == 'refs/heads/main' }} + # with: + # github_token: ${{ secrets.GITHUB_TOKEN }} + # publish_dir: ./docs/_build/html From 0111a2c74dcc1f8b7c868def0c415ef04ec9fb98 Mon Sep 17 00:00:00 2001 From: Philipp van Kempen Date: Fri, 26 Apr 2024 15:08:07 +0200 Subject: [PATCH 09/30] doct add initial autodoc files --- docs/docs.rst | 7 +++++++ docs/index.rst | 1 + docs/modules.rst | 7 +++++++ 3 files changed, 15 insertions(+) create mode 100644 docs/docs.rst create mode 100644 docs/modules.rst diff --git a/docs/docs.rst b/docs/docs.rst new file mode 100644 index 00000000..68623ee3 --- /dev/null +++ b/docs/docs.rst @@ -0,0 +1,7 @@ +Documentation +============= + +.. toctree:: + :maxdepth: 4 + + modules diff --git a/docs/index.rst b/docs/index.rst index 948c9380..3c8a830b 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -6,6 +6,7 @@ Seal5 documentation :caption: Contents: readme + docs Indices and tables ================== diff --git a/docs/modules.rst b/docs/modules.rst new file mode 100644 index 00000000..cdbeb97e --- /dev/null +++ b/docs/modules.rst @@ -0,0 +1,7 @@ +mlonmcu +======= + +.. toctree:: + :maxdepth: 4 + + seal5 From 2901ae14f723bf82864e4139d21e4271601f4e88 Mon Sep 17 00:00:00 2001 From: Philipp van Kempen Date: Fri, 26 Apr 2024 15:28:01 +0200 Subject: [PATCH 10/30] fix docs --- docs/.gitignore | 3 +- docs/conf.py | 178 ++++++----------------------------------------- docs/docs.rst | 7 -- docs/index.rst | 18 ++++- docs/make.bat | 35 ++++++++++ docs/modules.rst | 7 -- 6 files changed, 72 insertions(+), 176 deletions(-) delete mode 100644 docs/docs.rst create mode 100644 docs/make.bat delete mode 100644 docs/modules.rst diff --git a/docs/.gitignore b/docs/.gitignore index e35d8850..8b5ebe60 100644 --- a/docs/.gitignore +++ b/docs/.gitignore @@ -1 +1,2 @@ -_build +_build/ +_autosummary/ diff --git a/docs/conf.py b/docs/conf.py index d3e9fe30..745a98c5 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -1,169 +1,31 @@ -#!/usr/bin/env python -# -# Copyright (c) 2024 TUM Department of Electrical and Computer Engineering. -# -# This file is part of Seal5. -# See https://github.com/tum-ei-eda/seal5.git for further info. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. +# Configuration file for the Sphinx documentation builder. # +# For the full list of built-in configuration values, see the documentation: +# https://www.sphinx-doc.org/en/master/usage/configuration.html -# If extensions (or modules to document with autodoc) are in another -# directory, add these directories to sys.path here. If the directory is -# relative to the documentation root, use os.path.abspath to make it -# absolute, like shown here. -# -import os -import sys - -sys.path.insert(0, os.path.abspath("..")) +# -- Project information ----------------------------------------------------- +# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information -# pylint: disable=wrong-import-position -import seal5.version # noqa: E402 +project = 'Seal5' +copyright = '2024, TUM Department of Electrical and Computer Engineering - Chair of Electronic Design Automation' +author = 'TUM Department of Electrical and Computer Engineering - Chair of Electronic Design Automation' +release = 'v0.1.0' -# -- General configuration --------------------------------------------- - -# If your documentation needs a minimal Sphinx version, state it here. -# -# needs_sphinx = '1.0' +# -- General configuration --------------------------------------------------- +# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration -# Add any Sphinx extension module names here, as strings. They can be -# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom ones. -extensions = ["sphinx.ext.autodoc", "sphinx.ext.viewcode", "myst_parser", "numpydoc", "sphinxemoji.sphinxemoji"] +extensions = ["sphinx.ext.autodoc", "sphinx.ext.autosummary", "sphinx.ext.viewcode", "myst_parser", "numpydoc", "sphinxemoji.sphinxemoji"] numpydoc_show_class_members = False +autosummary_generate = True # Turn on sphinx.ext.autosummary -# Add any paths that contain templates here, relative to this directory. -templates_path = ["_templates"] - -# The suffix(es) of source filenames. -# You can specify multiple suffix as a list of string: -# -# source_suffix = ['.rst', '.md'] -source_suffix = ".rst" - -# The master toctree document. -master_doc = "index" - -# General information about the project. -project = "ML on MCU" -copyright = "2021, TUM Department of Electrical and Computer Engineering - Chair of Electronic Design Automation" -author = "TUM Department of Electrical and Computer Engineering - Chair of Electronic Design Automation" - -# The version info for the project you're documenting, acts as replacement -# for |version| and |release|, also used in various other places throughout -# the built documents. -# -# The short X.Y version. -version = seal5.version.__version__ -# The full version, including alpha/beta/rc tags. -release = seal5.version.__version__ - -# The language for content autogenerated by Sphinx. Refer to documentation -# for a list of supported languages. -# -# This is also used if you do content translation via gettext catalogs. -# Usually you set "language" from the command line for these cases. -language = "en" - -# List of patterns, relative to source directory, that match files and -# directories to ignore when looking for source files. -# This patterns also effect to html_static_path and html_extra_path -exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"] - -# The name of the Pygments (syntax highlighting) style to use. -pygments_style = "sphinx" - -# If true, `todo` and `todoList` produce output, else they produce nothing. -todo_include_todos = False - - -# -- 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' -html_theme = "sphinx_rtd_theme" - -# Theme options are theme-specific and customize the look and feel of a -# theme further. For a list of options available for each theme, see the -# documentation. -# -# html_theme_options = {} - -# 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 = ["_static"] - - -# -- Options for HTMLHelp output --------------------------------------- - -# Output file base name for HTML help builder. -htmlhelp_basename = "seal5doc" - - -# -- Options for LaTeX output ------------------------------------------ - -latex_elements = { - # The paper size ('letterpaper' or 'a4paper'). - # - # 'papersize': 'letterpaper', - # The font size ('10pt', '11pt' or '12pt'). - # - # 'pointsize': '10pt', - # Additional stuff for the LaTeX preamble. - # - # 'preamble': '', - # Latex figure (float) alignment - # - # 'figure_align': 'htbp', -} - -# Grouping the document tree into LaTeX files. List of tuples -# (source start file, target name, title, author, documentclass -# [howto, manual, or own class]). -latex_documents = [ - ( - master_doc, - "seal5.tex", - "Seal5 Documentation", - "TUM Department of Electrical and Computer Engineering - Chair of Electronic Design Automation", - "manual", - ), -] - - -# -- Options for manual page output ------------------------------------ +templates_path = ['_templates'] +exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store'] -# One entry per manual page. List of tuples -# (source start file, name, description, authors, manual section). -man_pages = [(master_doc, "seal5", "Seal5 Documentation", [author], 1)] +root_doc = 'index' -# -- Options for Texinfo output ---------------------------------------- +# -- Options for HTML output ------------------------------------------------- +# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output -# Grouping the document tree into Texinfo files. List of tuples -# (source start file, target name, title, author, -# dir menu entry, description, category) -texinfo_documents = [ - ( - master_doc, - "seal5", - "Seal5 Documentation", - author, - "seal5", - "One line description of project.", - "Miscellaneous", - ), -] +html_theme = 'alabaster' +html_static_path = ['_static'] diff --git a/docs/docs.rst b/docs/docs.rst deleted file mode 100644 index 68623ee3..00000000 --- a/docs/docs.rst +++ /dev/null @@ -1,7 +0,0 @@ -Documentation -============= - -.. toctree:: - :maxdepth: 4 - - modules diff --git a/docs/index.rst b/docs/index.rst index 3c8a830b..00f863bd 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -1,15 +1,27 @@ -Seal5 documentation -=================== +.. Seal5 documentation master file, created by + sphinx-quickstart on Fri Apr 26 15:11:01 2024. + You can adapt this file completely to your liking, but it should at least + contain the root `toctree` directive. + +Welcome to Seal5's documentation! +================================= + +.. autosummary:: + :toctree: _autosummary + :recursive: + + seal5 .. toctree:: :maxdepth: 2 :caption: Contents: readme - docs + Indices and tables ================== + * :ref:`genindex` * :ref:`modindex` * :ref:`search` diff --git a/docs/make.bat b/docs/make.bat new file mode 100644 index 00000000..32bb2452 --- /dev/null +++ b/docs/make.bat @@ -0,0 +1,35 @@ +@ECHO OFF + +pushd %~dp0 + +REM Command file for Sphinx documentation + +if "%SPHINXBUILD%" == "" ( + set SPHINXBUILD=sphinx-build +) +set SOURCEDIR=. +set BUILDDIR=_build + +%SPHINXBUILD% >NUL 2>NUL +if errorlevel 9009 ( + echo. + echo.The 'sphinx-build' command was not found. Make sure you have Sphinx + echo.installed, then set the SPHINXBUILD environment variable to point + echo.to the full path of the 'sphinx-build' executable. Alternatively you + echo.may add the Sphinx directory to PATH. + echo. + echo.If you don't have Sphinx installed, grab it from + echo.https://www.sphinx-doc.org/ + exit /b 1 +) + +if "%1" == "" goto help + +%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% +goto end + +:help +%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% + +:end +popd diff --git a/docs/modules.rst b/docs/modules.rst deleted file mode 100644 index cdbeb97e..00000000 --- a/docs/modules.rst +++ /dev/null @@ -1,7 +0,0 @@ -mlonmcu -======= - -.. toctree:: - :maxdepth: 4 - - seal5 From 038eb90e8edca3b91cc34a319bf94cb6726a1ffe Mon Sep 17 00:00:00 2001 From: Philipp van Kempen Date: Fri, 26 Apr 2024 15:31:08 +0200 Subject: [PATCH 11/30] fix docs --- docs/conf.py | 3 ++- docs/requirements.txt | 2 +- 2 files changed, 3 insertions(+), 2 deletions(-) diff --git a/docs/conf.py b/docs/conf.py index 745a98c5..2346ca17 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -27,5 +27,6 @@ # -- Options for HTML output ------------------------------------------------- # https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output -html_theme = 'alabaster' +# html_theme = 'alabaster' +html_theme = 'sphinx_rtd_theme' html_static_path = ['_static'] diff --git a/docs/requirements.txt b/docs/requirements.txt index a8e12d4f..0c1a71fe 100644 --- a/docs/requirements.txt +++ b/docs/requirements.txt @@ -2,5 +2,5 @@ Sphinx>=5.0 myst-parser numpydoc -sphinx_rtd_theme +sphinx-rtd-theme sphinxemoji From 4591e0cdac9f667a795390be972518dd8e36207f Mon Sep 17 00:00:00 2001 From: Thomas Goodfellow Date: Tue, 14 May 2024 12:09:31 +0200 Subject: [PATCH 12/30] Example extension tidy-up Moved coredsl to own rv_example sub-directory, added test case --- examples/cdsl/{ => rv_example}/Example.core_desc | 2 +- examples/cdsl/rv_example/test_subincacc.c | 15 +++++++++++++++ examples/cdsl/rv_example/test_subincacc.o | Bin 0 -> 760 bytes examples/demo.py | 2 +- 4 files changed, 17 insertions(+), 2 deletions(-) rename examples/cdsl/{ => rv_example}/Example.core_desc (91%) create mode 100644 examples/cdsl/rv_example/test_subincacc.c create mode 100644 examples/cdsl/rv_example/test_subincacc.o diff --git a/examples/cdsl/Example.core_desc b/examples/cdsl/rv_example/Example.core_desc similarity index 91% rename from examples/cdsl/Example.core_desc rename to examples/cdsl/rv_example/Example.core_desc index a9c130b0..23b4f0fd 100644 --- a/examples/cdsl/Example.core_desc +++ b/examples/cdsl/rv_example/Example.core_desc @@ -1,4 +1,4 @@ -import "rv_base/RV32I.core_desc" +import "../rv_base/RV32I.core_desc" // InstructionSet XExample extends RISCVBase { InstructionSet XExample extends RV32I { diff --git a/examples/cdsl/rv_example/test_subincacc.c b/examples/cdsl/rv_example/test_subincacc.c new file mode 100644 index 00000000..eec89923 --- /dev/null +++ b/examples/cdsl/rv_example/test_subincacc.c @@ -0,0 +1,15 @@ +// Test the SubIncAcc instruction of the TUM "example" extension. +// After calling the function the value 10 should be present in +// register a0, where an integer return value would be expected +// +// Compile with the "example" extension specified: +// clang test_subincacc.c -c --target=riscv32 -march=rv32ixexample +// then disassembly shows the new instruction: +// llvm-objdump -d test_subincacc.o --disassembler-options=numeric + +__attribute__((naked)) void test_subincacc() { + asm("li a0, 11"); + asm("li a1, 5"); + asm("li a2, 7"); + asm("cv_subincacc a0, a1, a2"); +} diff --git a/examples/cdsl/rv_example/test_subincacc.o b/examples/cdsl/rv_example/test_subincacc.o new file mode 100644 index 0000000000000000000000000000000000000000..f04a250b7047c57b7a9bf2460d9fb997f52f5960 GIT binary patch literal 760 zcmZWm%}&BV5S|KEk3`QV#F&UNF5QBno;302Vw8(#*lri7mbPgZf?o6;d=V}tzJTxG zYZxB@XRwQ)lgxhK*ZJC=={%iZU09X{CM@`ZUj^`%i~7`1fmN)o+hcgKo3Or|!0zjN z6J#i&Zh5HEEQq5rKV+OasVrA|S|{0Ywb~7IZ{RT*_p4zz{5kfLG`>?(Gc1-pUORAk z-It=SRLyann&*fkwE&=+CW+?+3B$625!PzBQ+BJ zBvd?c%s4Z=nK66^J|~ZJ8ej6}S1|(7_*~?Lt4WOTj0rRc1@%K=d_Cm2omqS!YhzN~#-usu&TstHYcBu* literal 0 HcmV?d00001 diff --git a/examples/demo.py b/examples/demo.py index a94ec41e..b2438e8c 100644 --- a/examples/demo.py +++ b/examples/demo.py @@ -62,7 +62,7 @@ # Load CoreDSL inputs cdsl_files = [ - EXAMPLES_DIR / "cdsl" / "Example.core_desc", + EXAMPLES_DIR / "cdsl" / "rv_example" / "Example.core_desc", ] seal5_flow.load(cdsl_files, verbose=VERBOSE, overwrite=True) From a4270497d90ba09b7eb9aca9b85d590300cec6d7 Mon Sep 17 00:00:00 2001 From: Thomas Goodfellow Date: Tue, 14 May 2024 12:17:45 +0200 Subject: [PATCH 13/30] Removed dangling file --- examples/cdsl/s4e-mac.core_desc | 73 --------------------------------- 1 file changed, 73 deletions(-) delete mode 100644 examples/cdsl/s4e-mac.core_desc diff --git a/examples/cdsl/s4e-mac.core_desc b/examples/cdsl/s4e-mac.core_desc deleted file mode 100644 index b1b78b3a..00000000 --- a/examples/cdsl/s4e-mac.core_desc +++ /dev/null @@ -1,73 +0,0 @@ -import "CoreDSL-Instruction-Set-Description/RISCVBase.core_desc" - -InstructionSet X_S4E_MAC extends RISCVBase { - architectural_state { - register unsigned<64> ACC; - } - - instructions { - RESET_ACC { // v-- funct7 v-- funct3 - encoding: 7'd0 :: 10'b0 :: 3'd0 :: 5'b0 :: 7'b0001011; - assembly:""; - behavior: ACC = 0; - } - - GET_ACC_LO { - encoding: 7'd1 :: 10'b0 :: 3'd0 :: rd[4:0] :: 7'b0001011; - assembly:"{name(rd)}"; - behavior: if (rd != 0) X[rd] = ACC[31:0]; - } - - GET_ACC_HI { - encoding: 7'd2 :: 10'b0 :: 3'd0 :: rd[4:0] :: 7'b0001011; - assembly:"{name(rd)}"; - behavior: if (rd != 0) X[rd] = ACC[63:32]; - } - - MACU_32 { - encoding: 7'd0 :: rs2[4:0] :: rs1[4:0] :: 3'd1 :: 5'b0 :: 7'b0001011; - assembly:"{name(rs1)}, {name(rs2)}"; - behavior: { - unsigned<64> mul = X[rs1] * X[rs2]; - unsigned<33> add = mul[31:0] + ACC[31:0]; - ACC = add[31:0]; - } - } - - MACS_32 { - encoding: 7'd1 :: rs2[4:0] :: rs1[4:0] :: 3'd1 :: 5'b0 :: 7'b0001011; - assembly:"{name(rs1)}, {name(rs2)}"; - behavior: { - signed<64> mul = ((signed) X[rs1]) * ((signed) X[rs2]); - signed<33> add = ((signed) mul[31:0]) + ((signed) ACC[31:0]); - ACC = add[31:0]; // bit range always yields unsigned type - } - } - - MACU_64 { - encoding: 7'd0 :: rs2[4:0] :: rs1[4:0] :: 3'd2 :: 5'b0 :: 7'b0001011; - assembly:"{name(rs1)}, {name(rs2)}"; - behavior: { - unsigned<64> mul = X[rs1] * X[rs2]; - unsigned<65> add = mul + ACC; - ACC = add[63:0]; - } - } - - MACS_64 { - encoding: 7'd1 :: rs2[4:0] :: rs1[4:0] :: 3'd2 :: 5'b0 :: 7'b0001011; - assembly:"{name(rs1)}, {name(rs2)}"; - behavior: { - signed<64> mul = ((signed) X[rs1]) * ((signed) X[rs2]); - signed<65> add = mul + ((signed) ACC); - ACC = add[63:0]; - } - } - } -} - -Core X_S4E_MAC provides X_S4E_MAC { - architectural_state { - register unsigned<64> dummy; - } -} From 8c99fdc1a4b66baf66db4d93b03466ee53c48462 Mon Sep 17 00:00:00 2001 From: Philipp van Kempen Date: Wed, 15 May 2024 08:46:26 +0200 Subject: [PATCH 14/30] coredsl2 writer: surround operands in parentheses --- seal5/backends/coredsl2/visitor.py | 23 ++++++++++++++++------- 1 file changed, 16 insertions(+), 7 deletions(-) diff --git a/seal5/backends/coredsl2/visitor.py b/seal5/backends/coredsl2/visitor.py index 391ffe46..91505acd 100644 --- a/seal5/backends/coredsl2/visitor.py +++ b/seal5/backends/coredsl2/visitor.py @@ -31,26 +31,31 @@ def operation(self: behav.Operation, writer): def binary_operation(self: behav.BinaryOperation, writer): # print("binary_operation") + writer.write("(") self.left = self.left.generate(writer) - writer.write(f" {self.op.value} ") + writer.write(f") {self.op.value} (") self.right = self.right.generate(writer) + writer.write(")") def slice_operation(self: behav.SliceOperation, writer): # print("slice_operation") self.expr = self.expr.generate(writer) - writer.write("[") + writer.write("[(") self.left = self.left.generate(writer) - writer.write(":") + writer.write("):(") self.right = self.right.generate(writer) - writer.write("]") + writer.write(")]") def concat_operation(self: behav.ConcatOperation, writer): # print("concat_operation") + # TODO: only add () where required + writer.write("(") self.left = self.left.generate(writer) - writer.write(" :: ") + writer.write(") :: (") self.right = self.right.generate(writer) + writer.write(")") def number_literal(self: behav.IntLiteral, writer): @@ -128,11 +133,13 @@ def loop(self: behav.Loop, writer): def ternary(self: behav.Ternary, writer): # print("ternary") + writer.write("(") self.cond.generate(writer) - writer.write(" ? ") + writer.write(") ? (") self.then_expr.generate(writer) - writer.write(" : ") + writer.write(") : (") self.else_expr.generate(writer) + writer.write(")") def return_(self: behav.Return, writer): @@ -147,7 +154,9 @@ def return_(self: behav.Return, writer): def unary_operation(self: behav.UnaryOperation, writer): # print("unary_operation") writer.write(self.op.value) + writer.write("(") self.right.generate(writer) + writer.write(")") def named_reference(self: behav.NamedReference, writer): From 19176aa1b6d80eccc73784075e9da19078babce5 Mon Sep 17 00:00:00 2001 From: Philipp van Kempen Date: Wed, 15 May 2024 11:36:24 +0200 Subject: [PATCH 15/30] examples/cfg/filter.yml: cleanup --- examples/cfg/filter.yml | 33 +++++++++++++++++++++++++-------- 1 file changed, 25 insertions(+), 8 deletions(-) diff --git a/examples/cfg/filter.yml b/examples/cfg/filter.yml index dd8c9538..083c0446 100644 --- a/examples/cfg/filter.yml +++ b/examples/cfg/filter.yml @@ -1,16 +1,33 @@ --- filter: sets: - # keep: [XCoreVSimd] - # drop: [RISCVBase, RISCVEncoding, Zicsr, Zifencei, RVSMode, RVDebug, RV32I, RVNMode, XCoreVSimd] - drop: [RISCVBase, RISCVEncoding, Zicsr, Zifencei, RVSMode, RVDebug, RV32I, RVNMode] - # drop: [RISCVBase, RISCVEncoding, Zicsr, Zifencei, RVSMode, RVDebug, RV32I, RVNMode, RV32Zpsfoperand] + drop: + - RISCVBase + - RISCVEncoding + - Zicsr + - Zifencei + - RVSMode + - RVDebug + - RV32I + - RVNMod instructions: - # keep: [CV_ABS, CV_ADD_B] - # keep: [SEAL5_simd_add16] # drop: [CV_CLIPU, CV_CLIPR, CV_CLIPUR, CV_SLET, CV_SLETU, SEAL5_CV_SHUFFLE2_B, SEAL5_CV_SHUFFLE2_H, ".*_(SC|SCI)_.*"] - drop: [SEAL5_CV_CLIPU, SEAL5_CV_CLIPR, SEAL5_CV_CLIPUR, SEAL5_CV_SLET, SEAL5_CV_SLETU, SEAL5_CV_PACK, SEAL5_CV_PACKLO_B] + drop: + - SEAL5_CV_CLIPU + - SEAL5_CV_CLIPR + - SEAL5_CV_CLIPUR + - SEAL5_CV_SLET + - SEAL5_CV_SLETU + - SEAL5_CV_PACK + - SEAL5_CV_PACKLO_B opcodes: - keep: [custom-0, custom-1, custom-2 ,custom-3, 0b00000, OP-P, OP] + keep: + - custom-0 + - custom-1 + - custom-2 + - custom-3 + - 0b00000 + - OP-P + - OP encoding_sizes: keep: [32] From 5c0161b84a05cb2424445218273c8be72b8d79be Mon Sep 17 00:00:00 2001 From: Philipp van Kempen Date: Wed, 15 May 2024 13:20:59 +0200 Subject: [PATCH 16/30] examples/cfg/[xcorev]/filter.yml: cleanup --- examples/cfg/filter.yml | 9 +---- examples/cfg/xcorev/filter.yml | 64 ++++++++++++++++++++++++++++++++-- 2 files changed, 62 insertions(+), 11 deletions(-) diff --git a/examples/cfg/filter.yml b/examples/cfg/filter.yml index 083c0446..6c61233b 100644 --- a/examples/cfg/filter.yml +++ b/examples/cfg/filter.yml @@ -12,14 +12,7 @@ filter: - RVNMod instructions: # drop: [CV_CLIPU, CV_CLIPR, CV_CLIPUR, CV_SLET, CV_SLETU, SEAL5_CV_SHUFFLE2_B, SEAL5_CV_SHUFFLE2_H, ".*_(SC|SCI)_.*"] - drop: - - SEAL5_CV_CLIPU - - SEAL5_CV_CLIPR - - SEAL5_CV_CLIPUR - - SEAL5_CV_SLET - - SEAL5_CV_SLETU - - SEAL5_CV_PACK - - SEAL5_CV_PACKLO_B + drop: [] opcodes: keep: - custom-0 diff --git a/examples/cfg/xcorev/filter.yml b/examples/cfg/xcorev/filter.yml index fc0d0c70..dab5e033 100644 --- a/examples/cfg/xcorev/filter.yml +++ b/examples/cfg/xcorev/filter.yml @@ -1,8 +1,66 @@ --- filter: sets: - drop: [RISCVBase, RISCVEncoding, Zicsr, Zifencei, RVSMode, RVDebug, RV32I, RVNMode] + drop: + - RISCVBase + - RISCVEncoding + - Zicsr + - Zifencei + - RVSMode + - RVDebug + - RV32I + - RVNMod instructions: - drop: [SEAL5_CV_CLIPU, SEAL5_CV_CLIPR, SEAL5_CV_CLIPUR, SEAL5_CV_SLET, SEAL5_CV_SLETU, SEAL5_CV_PACK, SEAL5_CV_PACKLO_B] + # drop: [CV_CLIPU, CV_CLIPR, CV_CLIPUR, CV_SLET, CV_SLETU, SEAL5_CV_SHUFFLE2_B, SEAL5_CV_SHUFFLE2_H, ".*_(SC|SCI)_.*"] + drop: + - SEAL5_CV_CLIPU + - SEAL5_CV_CLIPR + - SEAL5_CV_CLIPUR + - SEAL5_CV_SLET + - SEAL5_CV_SLETU + - SEAL5_CV_PACK + - SEAL5_CV_PACKLO_B + # broken due to pattern freeze + - SEAL5_CV_MACUN + - SEAL5_CV_MULURN + - SEAL5_CV_MULSRN + - SEAL5_CV_MACHHSN + - SEAL5_CV_MULHHURN + - SEAL5_CV_MACHHUN + - SEAL5_CV_MACSN + - SEAL5_CV_MULHHSRN + - SEAL5_CV_MACHHSRN + - SEAL5_CV_MACSRN + - SEAL5_CV_SDOTUSP_SC_H + - SEAL5_CV_SDOTSP_SC_H + - SEAL5_CV_SDOTUP_SC_B + - SEAL5_CV_SDOTUP_B + - SEAL5_CV_DOTSP_SC_H + - SEAL5_CV_SDOTSP_H + - SEAL5_CV_SDOTUSP_H + - SEAL5_CV_DOTSP_SCI_B + - SEAL5_CV_DOTUSP_SCI_H + - SEAL5_CV_SDOTUP_SCI_B + - SEAL5_CV_DOTUSP_SC_H + - SEAL5_CV_SDOTUSP_B + - SEAL5_CV_SDOTSP_SCI_H + - SEAL5_CV_DOTUSP_B + - SEAL5_CV_SDOTUSP_SCI_B + - SEAL5_CV_SDOTUSP_SC_B + - SEAL5_CV_DOTUSP_H + - SEAL5_CV_SDOTSP_SCI_B + - SEAL5_CV_SDOTSP_B + - SEAL5_CV_DOTUP_SCI_B + - SEAL5_CV_SDOTUP_H + - SEAL5_CV_SDOTSP_SC_B opcodes: - keep: [custom-0, custom-1, custom-2 ,custom-3, 0b00000, OP-P, OP] + keep: + - custom-0 + - custom-1 + - custom-2 + - custom-3 + - 0b00000 + - OP-P + - OP + encoding_sizes: + keep: [32] From a15d83cf0f82576718ae18212f8cac84334aa93e Mon Sep 17 00:00:00 2001 From: Philipp van Kempen Date: Thu, 23 May 2024 08:32:40 +0200 Subject: [PATCH 17/30] Update docs.yml --- .github/workflows/docs.yml | 15 +++++++-------- 1 file changed, 7 insertions(+), 8 deletions(-) diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index fff64d7c..b03c9451 100644 --- a/.github/workflows/docs.yml +++ b/.github/workflows/docs.yml @@ -41,15 +41,14 @@ jobs: source .venv/bin/activate cd docs make html - - name: Archive environment (without deps) + - name: Store docs as an artifact uses: actions/upload-artifact@v2 with: name: html-docs path: docs/_build/html - # TODO: enable after open source release - # - name: Deploy docs - # uses: peaceiris/actions-gh-pages@v3 - # if: ${{ github.ref == 'refs/heads/main' }} - # with: - # github_token: ${{ secrets.GITHUB_TOKEN }} - # publish_dir: ./docs/_build/html + - name: Deploy docs + uses: peaceiris/actions-gh-pages@v3 + if: ${{ github.ref == 'refs/heads/main' }} + with: + github_token: ${{ secrets.GITHUB_TOKEN }} + publish_dir: ./docs/_build/html From 99c4d34ed32e70a3ddd967bf4747d18265fd70bd Mon Sep 17 00:00:00 2001 From: Philipp van Kempen Date: Thu, 23 May 2024 09:14:09 +0200 Subject: [PATCH 18/30] Create .readthedocs.yaml --- .readthedocs.yaml | 31 +++++++++++++++++++++++++++++++ 1 file changed, 31 insertions(+) create mode 100644 .readthedocs.yaml diff --git a/.readthedocs.yaml b/.readthedocs.yaml new file mode 100644 index 00000000..b9dade10 --- /dev/null +++ b/.readthedocs.yaml @@ -0,0 +1,31 @@ +# Read the Docs configuration file +# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details + +# Required +version: 2 + +# Set the OS, Python version and other tools you might need +build: + os: ubuntu-22.04 + tools: + python: "3.12" + # You can also specify other tool versions: + # nodejs: "19" + # rust: "1.64" + # golang: "1.19" + +# Build documentation in the "docs/" directory with Sphinx +sphinx: + configuration: docs/conf.py + +# Optionally build your docs in additional formats such as PDF and ePub +formats: + - pdf +# - epub + +# Optional but recommended, declare the Python requirements required +# to build your documentation +# See https://docs.readthedocs.io/en/stable/guides/reproducible-builds.html +python: + install: + - requirements: docs/requirements.txt From f318767c0767665711e1fdfe9cd4f114af35f928 Mon Sep 17 00:00:00 2001 From: Philipp van Kempen Date: Thu, 23 May 2024 09:17:36 +0200 Subject: [PATCH 19/30] Create LICENSE --- LICENSE | 201 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 201 insertions(+) create mode 100644 LICENSE diff --git a/LICENSE b/LICENSE new file mode 100644 index 00000000..7dfb48ea --- /dev/null +++ b/LICENSE @@ -0,0 +1,201 @@ + Apache License + Version 2.0, January 2004 + http://www.apache.org/licenses/ + + TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION + + 1. Definitions. + + "License" shall mean the terms and conditions for use, reproduction, + and distribution as defined by Sections 1 through 9 of this document. + + "Licensor" shall mean the copyright owner or entity authorized by + the copyright owner that is granting the License. + + "Legal Entity" shall mean the union of the acting entity and all + other entities that control, are controlled by, or are under common + control with that entity. For the purposes of this definition, + "control" means (i) the power, direct or indirect, to cause the + direction or management of such entity, whether by contract or + otherwise, or (ii) ownership of fifty percent (50%) or more of the + outstanding shares, or (iii) beneficial ownership of such entity. + + "You" (or "Your") shall mean an individual or Legal Entity + exercising permissions granted by this License. + + "Source" form shall mean the preferred form for making modifications, + including but not limited to software source code, documentation + source, and configuration files. + + "Object" form shall mean any form resulting from mechanical + transformation or translation of a Source form, including but + not limited to compiled object code, generated documentation, + and conversions to other media types. + + "Work" shall mean the work of authorship, whether in Source or + Object form, made available under the License, as indicated by a + copyright notice that is included in or attached to the work + (an example is provided in the Appendix below). + + "Derivative Works" shall mean any work, whether in Source or Object + form, that is based on (or derived from) the Work and for which the + editorial revisions, annotations, elaborations, or other modifications + represent, as a whole, an original work of authorship. For the purposes + of this License, Derivative Works shall not include works that remain + separable from, or merely link (or bind by name) to the interfaces of, + the Work and Derivative Works thereof. + + "Contribution" shall mean any work of authorship, including + the original version of the Work and any modifications or additions + to that Work or Derivative Works thereof, that is intentionally + submitted to Licensor for inclusion in the Work by the copyright owner + or by an individual or Legal Entity authorized to submit on behalf of + the copyright owner. For the purposes of this definition, "submitted" + means any form of electronic, verbal, or written communication sent + to the Licensor or its representatives, including but not limited to + communication on electronic mailing lists, source code control systems, + and issue tracking systems that are managed by, or on behalf of, the + Licensor for the purpose of discussing and improving the Work, but + excluding communication that is conspicuously marked or otherwise + designated in writing by the copyright owner as "Not a Contribution." + + "Contributor" shall mean Licensor and any individual or Legal Entity + on behalf of whom a Contribution has been received by Licensor and + subsequently incorporated within the Work. + + 2. Grant of Copyright License. Subject to the terms and conditions of + this License, each Contributor hereby grants to You a perpetual, + worldwide, non-exclusive, no-charge, royalty-free, irrevocable + copyright license to reproduce, prepare Derivative Works of, + publicly display, publicly perform, sublicense, and distribute the + Work and such Derivative Works in Source or Object form. + + 3. Grant of Patent License. Subject to the terms and conditions of + this License, each Contributor hereby grants to You a perpetual, + worldwide, non-exclusive, no-charge, royalty-free, irrevocable + (except as stated in this section) patent license to make, have made, + use, offer to sell, sell, import, and otherwise transfer the Work, + where such license applies only to those patent claims licensable + by such Contributor that are necessarily infringed by their + Contribution(s) alone or by combination of their Contribution(s) + with the Work to which such Contribution(s) was submitted. If You + institute patent litigation against any entity (including a + cross-claim or counterclaim in a lawsuit) alleging that the Work + or a Contribution incorporated within the Work constitutes direct + or contributory patent infringement, then any patent licenses + granted to You under this License for that Work shall terminate + as of the date such litigation is filed. + + 4. Redistribution. You may reproduce and distribute copies of the + Work or Derivative Works thereof in any medium, with or without + modifications, and in Source or Object form, provided that You + meet the following conditions: + + (a) You must give any other recipients of the Work or + Derivative Works a copy of this License; and + + (b) You must cause any modified files to carry prominent notices + stating that You changed the files; and + + (c) You must retain, in the Source form of any Derivative Works + that You distribute, all copyright, patent, trademark, and + attribution notices from the Source form of the Work, + excluding those notices that do not pertain to any part of + the Derivative Works; and + + (d) If the Work includes a "NOTICE" text file as part of its + distribution, then any Derivative Works that You distribute must + include a readable copy of the attribution notices contained + within such NOTICE file, excluding those notices that do not + pertain to any part of the Derivative Works, in at least one + of the following places: within a NOTICE text file distributed + as part of the Derivative Works; within the Source form or + documentation, if provided along with the Derivative Works; or, + within a display generated by the Derivative Works, if and + wherever such third-party notices normally appear. The contents + of the NOTICE file are for informational purposes only and + do not modify the License. You may add Your own attribution + notices within Derivative Works that You distribute, alongside + or as an addendum to the NOTICE text from the Work, provided + that such additional attribution notices cannot be construed + as modifying the License. + + You may add Your own copyright statement to Your modifications and + may provide additional or different license terms and conditions + for use, reproduction, or distribution of Your modifications, or + for any such Derivative Works as a whole, provided Your use, + reproduction, and distribution of the Work otherwise complies with + the conditions stated in this License. + + 5. Submission of Contributions. Unless You explicitly state otherwise, + any Contribution intentionally submitted for inclusion in the Work + by You to the Licensor shall be under the terms and conditions of + this License, without any additional terms or conditions. + Notwithstanding the above, nothing herein shall supersede or modify + the terms of any separate license agreement you may have executed + with Licensor regarding such Contributions. + + 6. Trademarks. This License does not grant permission to use the trade + names, trademarks, service marks, or product names of the Licensor, + except as required for reasonable and customary use in describing the + origin of the Work and reproducing the content of the NOTICE file. + + 7. Disclaimer of Warranty. Unless required by applicable law or + agreed to in writing, Licensor provides the Work (and each + Contributor provides its Contributions) on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or + implied, including, without limitation, any warranties or conditions + of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A + PARTICULAR PURPOSE. You are solely responsible for determining the + appropriateness of using or redistributing the Work and assume any + risks associated with Your exercise of permissions under this License. + + 8. Limitation of Liability. In no event and under no legal theory, + whether in tort (including negligence), contract, or otherwise, + unless required by applicable law (such as deliberate and grossly + negligent acts) or agreed to in writing, shall any Contributor be + liable to You for damages, including any direct, indirect, special, + incidental, or consequential damages of any character arising as a + result of this License or out of the use or inability to use the + Work (including but not limited to damages for loss of goodwill, + work stoppage, computer failure or malfunction, or any and all + other commercial damages or losses), even if such Contributor + has been advised of the possibility of such damages. + + 9. Accepting Warranty or Additional Liability. While redistributing + the Work or Derivative Works thereof, You may choose to offer, + and charge a fee for, acceptance of support, warranty, indemnity, + or other liability obligations and/or rights consistent with this + License. However, in accepting such obligations, You may act only + on Your own behalf and on Your sole responsibility, not on behalf + of any other Contributor, and only if You agree to indemnify, + defend, and hold each Contributor harmless for any liability + incurred by, or claims asserted against, such Contributor by reason + of your accepting any such warranty or additional liability. + + END OF TERMS AND CONDITIONS + + APPENDIX: How to apply the Apache License to your work. + + To apply the Apache License to your work, attach the following + boilerplate notice, with the fields enclosed by brackets "[]" + replaced with your own identifying information. (Don't include + the brackets!) The text should be enclosed in the appropriate + comment syntax for the file format. We also recommend that a + file or class name and description of purpose be included on the + same "printed page" as the copyright notice for easier + identification within third-party archives. + + Copyright 2024 TUM Department of Electrical and Computer Engineering - Chair of Electronic Design Automation + + Licensed under the Apache License, Version 2.0 (the "License"); + you may not use this file except in compliance with the License. + You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. From 31faf262bfa0c7f74e1fa04e43b596ca4779eaaa Mon Sep 17 00:00:00 2001 From: Philipp van Kempen Date: Thu, 23 May 2024 09:23:20 +0200 Subject: [PATCH 20/30] Create release.yml --- .github/workflows/release.yml | 49 +++++++++++++++++++++++++++++++++++ 1 file changed, 49 insertions(+) create mode 100644 .github/workflows/release.yml diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml new file mode 100644 index 00000000..378e003e --- /dev/null +++ b/.github/workflows/release.yml @@ -0,0 +1,49 @@ +on: + push: + # Sequence of patterns matched against refs/tags + tags: + - 'v\d+.\d+.\d+' # Push events for v0.1.0, v20.15.10 but not v0.1.0dev0 + +name: Create Release + +jobs: + build: + name: Create Release + runs-on: ubuntu-latest + if: ${{ github.repository == 'tum-ei-eda/seal5' }} + steps: + - name: Checkout code + uses: actions/checkout@v3 + - name: Generate changelog + id: changelog + uses: metcalfc/changelog-generator@v0.4.3 + with: + myToken: ${{ secrets.GITHUB_TOKEN }} + - name: Create Release + id: create_release + uses: actions/create-release@v1 + env: + GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} # This token is provided by Actions, you do not need to create your own token + with: + tag_name: ${{ github.ref }} + release_name: Release ${{ github.ref }} + body: | + Changes in this Release: + ${{ steps.changelog.outputs.changelog }} + draft: true + prerelease: false + + + publish: + name: Publish to PyPI + runs-on: ubuntu-latest + if: ${{ github.repository == 'tum-ei-eda/seal5' }} + steps: + - name: Checkout code + uses: actions/checkout@v3 + - name: Build package + run: make dist + - name: Publish to PyPI + uses: pypa/gh-action-pypi-publish@release/v1 + with: + password: ${{ secrets.PYPI_API_TOKEN }} From aa7a071a130fa77a15a106c19564b1123156b947 Mon Sep 17 00:00:00 2001 From: Philipp van Kempen Date: Thu, 23 May 2024 09:33:13 +0200 Subject: [PATCH 21/30] update version: v0.1.1 --- docs/conf.py | 2 +- seal5/version.py | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/conf.py b/docs/conf.py index 2346ca17..4f6dfbbf 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -9,7 +9,7 @@ project = 'Seal5' copyright = '2024, TUM Department of Electrical and Computer Engineering - Chair of Electronic Design Automation' author = 'TUM Department of Electrical and Computer Engineering - Chair of Electronic Design Automation' -release = 'v0.1.0' +release = 'v0.1.1' # -- General configuration --------------------------------------------------- # https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration diff --git a/seal5/version.py b/seal5/version.py index 93a2ed9f..8e8e7a63 100644 --- a/seal5/version.py +++ b/seal5/version.py @@ -18,4 +18,4 @@ # """Version module for seal5.""" -__version__ = "0.1.0dev0" +__version__ = "0.1.1dev0" From 490dfe82389836ee04993daf85a6c45e48983394 Mon Sep 17 00:00:00 2001 From: Philipp van Kempen Date: Thu, 23 May 2024 09:37:28 +0200 Subject: [PATCH 22/30] [ci] update release.yml --- .github/workflows/release.yml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index 378e003e..98532619 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -16,7 +16,7 @@ jobs: uses: actions/checkout@v3 - name: Generate changelog id: changelog - uses: metcalfc/changelog-generator@v0.4.3 + uses: metcalfc/changelog-generator@v4.3.1 with: myToken: ${{ secrets.GITHUB_TOKEN }} - name: Create Release @@ -42,7 +42,7 @@ jobs: - name: Checkout code uses: actions/checkout@v3 - name: Build package - run: make dist + run: python -m build - name: Publish to PyPI uses: pypa/gh-action-pypi-publish@release/v1 with: From 8780a751ec9f04d1d26d5b5b5b27cf87bccc9167 Mon Sep 17 00:00:00 2001 From: Philipp van Kempen Date: Thu, 23 May 2024 09:37:39 +0200 Subject: [PATCH 23/30] update dev requirements --- requirements_dev.txt | 2 ++ 1 file changed, 2 insertions(+) diff --git a/requirements_dev.txt b/requirements_dev.txt index 3cf960d2..eb739bd0 100644 --- a/requirements_dev.txt +++ b/requirements_dev.txt @@ -2,3 +2,5 @@ black>=22.8.0 flake8 pylint +build +twine From 304b3395b5f07a8f45da8ae214033e208210ed49 Mon Sep 17 00:00:00 2001 From: Philipp van Kempen Date: Thu, 23 May 2024 09:41:07 +0200 Subject: [PATCH 24/30] [ci] update release.yml --- .github/workflows/release.yml | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index 98532619..747b5ed5 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -42,7 +42,9 @@ jobs: - name: Checkout code uses: actions/checkout@v3 - name: Build package - run: python -m build + run: | + python -m pip install -r requirments_dev.txt + python -m build - name: Publish to PyPI uses: pypa/gh-action-pypi-publish@release/v1 with: From 42ed8d9074f99efdc4a7c0057c1773cbafb30c0e Mon Sep 17 00:00:00 2001 From: Philipp van Kempen Date: Thu, 23 May 2024 09:42:21 +0200 Subject: [PATCH 25/30] [ci] update release.yml --- .github/workflows/release.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index 747b5ed5..99c23331 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -43,7 +43,7 @@ jobs: uses: actions/checkout@v3 - name: Build package run: | - python -m pip install -r requirments_dev.txt + python -m pip install -r requirements_dev.txt python -m build - name: Publish to PyPI uses: pypa/gh-action-pypi-publish@release/v1 From dc8049428c3561236f4ec70ce81ca61c7d299ceb Mon Sep 17 00:00:00 2001 From: Thomas Goodfellow Date: Thu, 23 May 2024 09:44:11 +0200 Subject: [PATCH 26/30] Example test case llvm-lit-ified --- examples/cdsl/rv_example/test_subincacc.c | 12 +++++++++++- examples/cdsl/rv_example/test_subincacc.o | Bin 760 -> 0 bytes 2 files changed, 11 insertions(+), 1 deletion(-) delete mode 100644 examples/cdsl/rv_example/test_subincacc.o diff --git a/examples/cdsl/rv_example/test_subincacc.c b/examples/cdsl/rv_example/test_subincacc.c index eec89923..d4a742c8 100644 --- a/examples/cdsl/rv_example/test_subincacc.c +++ b/examples/cdsl/rv_example/test_subincacc.c @@ -7,9 +7,19 @@ // then disassembly shows the new instruction: // llvm-objdump -d test_subincacc.o --disassembler-options=numeric +// For automated runs by llvm-lit: +// RUN: %clang -c -target riscv32-unknown-elf -march=rv32ixexample -o %t.o %s +// RUN: llvm-objdump --disassembler-options=numeric -d %t.o | FileCheck %s + + __attribute__((naked)) void test_subincacc() { + // Non-ISAX canary instruction, to flag an unwanted case of endian/width/compression/whatever + // CHECK: b3 01 52 00 add x3, x4, x5 + asm("add x3, x4, x5"); + asm("li a0, 11"); asm("li a1, 5"); asm("li a2, 7"); - asm("cv_subincacc a0, a1, a2"); + // CHECK: ab ba b5 51 cv_subincacc x21, x11, x27 + asm("cv_subincacc x21, x11, x27"); } diff --git a/examples/cdsl/rv_example/test_subincacc.o b/examples/cdsl/rv_example/test_subincacc.o deleted file mode 100644 index f04a250b7047c57b7a9bf2460d9fb997f52f5960..0000000000000000000000000000000000000000 GIT binary patch literal 0 HcmV?d00001 literal 760 zcmZWm%}&BV5S|KEk3`QV#F&UNF5QBno;302Vw8(#*lri7mbPgZf?o6;d=V}tzJTxG zYZxB@XRwQ)lgxhK*ZJC=={%iZU09X{CM@`ZUj^`%i~7`1fmN)o+hcgKo3Or|!0zjN z6J#i&Zh5HEEQq5rKV+OasVrA|S|{0Ywb~7IZ{RT*_p4zz{5kfLG`>?(Gc1-pUORAk z-It=SRLyann&*fkwE&=+CW+?+3B$625!PzBQ+BJ zBvd?c%s4Z=nK66^J|~ZJ8ej6}S1|(7_*~?Lt4WOTj0rRc1@%K=d_Cm2omqS!YhzN~#-usu&TstHYcBu* From 69e981db7cdbda5c511d07a592d3b039de9bc003 Mon Sep 17 00:00:00 2001 From: Philipp van Kempen Date: Thu, 23 May 2024 09:44:39 +0200 Subject: [PATCH 27/30] update version: v0.1.2 --- docs/conf.py | 2 +- seal5/version.py | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/conf.py b/docs/conf.py index 4f6dfbbf..dc1280c1 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -9,7 +9,7 @@ project = 'Seal5' copyright = '2024, TUM Department of Electrical and Computer Engineering - Chair of Electronic Design Automation' author = 'TUM Department of Electrical and Computer Engineering - Chair of Electronic Design Automation' -release = 'v0.1.1' +release = 'v0.1.2' # -- General configuration --------------------------------------------------- # https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration diff --git a/seal5/version.py b/seal5/version.py index 8e8e7a63..14afadef 100644 --- a/seal5/version.py +++ b/seal5/version.py @@ -18,4 +18,4 @@ # """Version module for seal5.""" -__version__ = "0.1.1dev0" +__version__ = "0.1.2" From 52769eb4831cb90fa6f4f6d185ef61a64ac86a86 Mon Sep 17 00:00:00 2001 From: Thomas Goodfellow Date: Thu, 23 May 2024 09:57:05 +0200 Subject: [PATCH 28/30] Submodule catchup --- examples/cdsl/rv_s4e | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/examples/cdsl/rv_s4e b/examples/cdsl/rv_s4e index c5d5d945..f5394e8e 160000 --- a/examples/cdsl/rv_s4e +++ b/examples/cdsl/rv_s4e @@ -1 +1 @@ -Subproject commit c5d5d9455499aac76426c60f78a9ced088a08054 +Subproject commit f5394e8e0438b0c7e4bf16273efc74b8335215cc From 0bd288fd30423b2914313c9b4a5a9dbdc5b5d559 Mon Sep 17 00:00:00 2001 From: Thomas Goodfellow Date: Thu, 23 May 2024 14:23:51 +0200 Subject: [PATCH 29/30] Added test case for example extension --- examples/corev_demo.py | 1 + examples/demo.py | 4 +++- examples/{cdsl/rv_example => tests/example}/test_subincacc.c | 2 +- 3 files changed, 5 insertions(+), 2 deletions(-) rename examples/{cdsl/rv_example => tests/example}/test_subincacc.c (92%) diff --git a/examples/corev_demo.py b/examples/corev_demo.py index 8c789455..17d43f8a 100644 --- a/examples/corev_demo.py +++ b/examples/corev_demo.py @@ -74,6 +74,7 @@ # Load test inputs test_files = [ EXAMPLES_DIR / "tests" / "xcorev" / "*.inline_asm.c", + EXAMPLES_DIR / "tests" / "xcorev" / "test_subincacc.c", ] seal5_flow.load(test_files, verbose=VERBOSE, overwrite=True) diff --git a/examples/demo.py b/examples/demo.py index b2438e8c..a9fcf87e 100644 --- a/examples/demo.py +++ b/examples/demo.py @@ -67,7 +67,9 @@ seal5_flow.load(cdsl_files, verbose=VERBOSE, overwrite=True) # Load test inputs -test_files = [] +test_files = [ + EXAMPLES_DIR / "tests" / "example" / "test_subincacc.c", +] seal5_flow.load(test_files, verbose=VERBOSE, overwrite=True) # Load YAML inputs diff --git a/examples/cdsl/rv_example/test_subincacc.c b/examples/tests/example/test_subincacc.c similarity index 92% rename from examples/cdsl/rv_example/test_subincacc.c rename to examples/tests/example/test_subincacc.c index d4a742c8..d68dcdc1 100644 --- a/examples/cdsl/rv_example/test_subincacc.c +++ b/examples/tests/example/test_subincacc.c @@ -8,7 +8,7 @@ // llvm-objdump -d test_subincacc.o --disassembler-options=numeric // For automated runs by llvm-lit: -// RUN: %clang -c -target riscv32-unknown-elf -march=rv32ixexample -o %t.o %s +// RUN: clang -c -target riscv32-unknown-elf -march=rv32ixexample -o %t.o %s // RUN: llvm-objdump --disassembler-options=numeric -d %t.o | FileCheck %s From 79c6eaeba6e5209898c895e7f3b837297864dfb6 Mon Sep 17 00:00:00 2001 From: Thomas Goodfellow Date: Thu, 23 May 2024 14:29:15 +0200 Subject: [PATCH 30/30] Reverting bad corev_demo.py push --- examples/corev_demo.py | 1 - 1 file changed, 1 deletion(-) diff --git a/examples/corev_demo.py b/examples/corev_demo.py index 17d43f8a..8c789455 100644 --- a/examples/corev_demo.py +++ b/examples/corev_demo.py @@ -74,7 +74,6 @@ # Load test inputs test_files = [ EXAMPLES_DIR / "tests" / "xcorev" / "*.inline_asm.c", - EXAMPLES_DIR / "tests" / "xcorev" / "test_subincacc.c", ] seal5_flow.load(test_files, verbose=VERBOSE, overwrite=True)