Add new documentation

Signed-off-by: Wojciech Rajtar <[email protected]>

Author: wrajtar

.github/workflows/build-docs.yml

@@ -24,22 +24,22 @@ jobs:
 
       - name: Build Docs
         run: |
-          pushd docs
+          pushd doc
             pip3 install -r requirements.txt
             TZ=UTC make html
           popd
-          ls -lah docs/build
+          ls -lah doc/build
 
       - name: Pack artifacts
         if: always()
         uses: actions/upload-artifact@v4
         with:
           name: docs
-          path: ./docs/build
+          path: ./doc/build
 
       - name: Deploy
         uses: peaceiris/actions-gh-pages@v4
         if: ${{ github.ref == 'refs/heads/main' }}
         with:
             github_token: ${{ secrets.GITHUB_TOKEN }}
-            publish_dir: ./docs/build/html
+            publish_dir: ./doc/build/html

doc/.gitignore

@@ -0,0 +1 @@
+.venv

doc/Makefile

@@ -0,0 +1,9 @@
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = source
+BUILDDIR      = build
+
+# Catch-all target: route all unknown targets to Sphinx using the "make mode" option.
+# $(O) is meant as a shortcut for $(SPHINXOPTS).
+%:
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

doc/requirements.txt

@@ -0,0 +1,2 @@
+Sphinx>=8.0
+https://github.com/antmicro/antmicro-sphinx-utils/archive/main.zip

doc/source/Makefile

@@ -0,0 +1,9 @@
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = source
+BUILDDIR      = build
+
+# Catch-all target: route all unknown targets to Sphinx using the "make mode" option.
+# $(O) is meant as a shortcut for $(SPHINXOPTS).
+%:
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

doc/source/ccc.md

@@ -0,0 +1,34 @@
+# I3C Common Command Codes (CCC)
+
+The I3C core supports all CCCs required by the I3C Basic spec, please see "Table 16 I3C Common Command Codes" for a full reference.
+
+All CCCs are exercised with Cocotb tests.
+
+## Broadcast CCCs
+
+The following Broadcast CCCs are currently supported by the core (all required Broadcast CCCs as per the errata, and one optional Broadcast CCC):
+
+* ENEC (R) - Enable Events Command
+* DISEC (R) - Disable Events Command
+* SETMWL (R) - Set Max Write Length
+* SETMRL (R) - Set Max Read Length
+* SETAASA (O) - Set All Addresses to Static Adresses
+* RSTACT (R) - Target Reset Action
+
+## Direct CCCs
+
+The following Direct CCCs are currently supported by the core (all required Direct CCCs, plus several optional/conditional ones):
+
+* ENEC (R) - Enable Events Command
+* DISEC (R) - Disable Events Command
+* RSTDAA (R) - Direct Reset Dynamic Address Assignment - this direct CCC is deprecated, the core NACKs this command as per the spec
+* SETDASA (O) - Set Dynamic Address from Static Address
+* SETMWL (R) - Set Max Write Length
+* SETMRL (R) - Set Max Read Length
+* GETMWL (R) - Get Max Write Length
+* GETMRL (R) - Set Max Read Length
+* GETPID (C) - Get Provisioned ID
+* GETBCR (C) - Get Bus Characteristics Register
+* GETDCR (C) - Get Device Characteristics Register
+* GETSTATUS (R) - Get Device Status
+* RSTACT (R) - Target Reset Action

doc/source/conf.py

@@ -0,0 +1,83 @@
+# -*- coding: utf-8 -*-
+#
+# This file is execfile()d with the current directory set to its containing dir.
+#
+# Note that not all possible configuration values are present in this file.
+#
+# All configuration values have a default; values that are commented out
+# serve to show the default.
+#
+# Updated documentation of the configuration options is available at
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+from datetime import datetime
+
+from antmicro_sphinx_utils.defaults import (
+    numfig_format,
+    extensions as default_extensions,
+    myst_enable_extensions as default_myst_enable_extensions,
+    myst_fence_as_directive as default_myst_fence_as_directive,
+    antmicro_html,
+    antmicro_latex
+)
+
+# 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.
+#sys.path.insert(0, os.path.abspath('.'))
+
+# -- General configuration -----------------------------------------------------
+
+# General information about the project.
+project = u'CHIPS Alliance Caliptra Open Source I3C core'
+basic_filename = u'i3c-core-docs'
+authors = u'Antmicro'
+copyright = f'{authors}, {datetime.now().year}'
+
+# The short X.Y version.
+version = ''
+# The full version, including alpha/beta/rc tags.
+release = ''
+
+# This is temporary before the clash between myst-parser and immaterial is fixed
+sphinx_immaterial_override_builtin_admonitions = False
+
+numfig = True
+
+# If you need to add extensions just add to those lists
+extensions = default_extensions
+myst_enable_extensions = default_myst_enable_extensions
+myst_fence_as_directive = default_myst_fence_as_directive
+
+myst_substitutions = {
+    "project": project
+}
+
+myst_heading_anchors = 4
+
+today_fmt = '%Y-%m-%d'
+
+todo_include_todos=False
+
+# -- Options for HTML output ---------------------------------------------------
+
+html_theme = 'sphinx_immaterial'
+
+html_last_updated_fmt = today_fmt
+
+html_show_sphinx = False
+
+(
+    html_logo,
+    html_theme_options,
+    html_context
+) = antmicro_html(pdf_url=f"{basic_filename}.pdf")
+
+html_title = project
+
+(
+    latex_elements,
+    latex_documents,
+    latex_logo,
+    latex_additional_files
+) = antmicro_latex(basic_filename, authors, project)

doc/source/dv.md

@@ -0,0 +1,29 @@
+# Design verification
+
+This chapter presents the available models and tools which are used for I3C verification.
+The core is verified with [the Cocotb + unit tests](https://github.com/chipsalliance/i3c-core/tree/main/verification/cocotb/block) and [the UVM test suite](https://github.com/chipsalliance/i3c-core/tree/main/verification/uvm_i3c).
+
+There are also non-public tests which utilize Avery I3C VIP framework. The tests include: `private_read`, `private_write` and `recovery` and verify operation of target mode private reads and writes and the secure firmware recovery flow respectively.
+
+## Testplans
+
+This section contains testplans for the verification.
+
+Definitions:
+* `testplan` - an organized collection of testpoints
+* `testpoint` - an actionable item, which can be turned into a test:
+    * `name` - typically related to the tested feature
+    * `desc` - detailed description; should contain description of the feature, configuration mode, stimuli, expected behavior.
+    * `stage` - can be used to assign testpoints to milestones.
+    * `tests` - names of implemented tests, which cover the testpoint. Relation test-testpoint can be many to many.
+    * `tags` - additional tags that can be used to group testpoints
+
+### Testplans for individual blocks
+
+```{include} ../../verification/testplan/generated/testplans_blocks.md
+```
+
+### Testplans for the core
+
+```{include} ../../verification/testplan/generated/testplans_core.md
+```