Migrate docs

Internal-tag: [#64059]
Signed-off-by: Michal Czyz <[email protected]>

.ci.yml

@@ -0,0 +1,34 @@
+stages:
+  - build
+  - deploy
+
+image: $CI_DOCS_DOCKER_IMAGE
+
+build:
+  stage: build
+  tags: ['ace-x86_64']
+  variables:
+    GIT_SUBMODULE_STRATEGY: normal
+  script:
+    - cd docs/
+    - pip3 install -r requirements.txt
+    - make html latexpdf
+    - cp build/latex/*.pdf build/html/
+    - tar cf $CI_DOCS_ARCHIVE -C build/html/ .
+    - mv $CI_DOCS_ARCHIVE build ..
+  artifacts:
+    paths:
+      - build
+      - $CI_DOCS_ARCHIVE
+
+deploy:
+  variables:
+    GIT_STRATEGY: none
+  dependencies:
+    - build
+  stage: deploy
+  tags: ['docs']
+  script: echo 'Deploying docs'
+  artifacts:
+    paths:
+      - $CI_DOCS_ARCHIVE

.github/workflows/build-docs.yml

@@ -0,0 +1,45 @@
+name: Documentation build
+
+on:
+  push:
+    branches: ["main"]
+
+permissions:
+  contents: write
+
+jobs:
+  build:
+    name: Build
+    runs-on: ubuntu-latest
+    env:
+      DEBIAN_FRONTEND: "noninteractive"
+    steps:
+      - name: Install dependencies
+        run: |
+          sudo apt -qqy update && sudo apt -qqy --no-install-recommends install \
+            python3 python3-pip
+
+      - name: Setup repository
+        uses: actions/checkout@v4
+
+      - name: Build Docs
+        run: |
+          pushd docs
+            pip3 install -r requirements.txt
+            TZ=UTC make html
+          popd
+          ls -lah docs/build
+
+      - name: Pack artifacts
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: docs
+          path: ./docs/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

docs/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)

docs/requirements.txt

@@ -0,0 +1 @@
+https://github.com/antmicro/antmicro-sphinx-utils/archive/main.zip

docs/source/ci_queues.md

@@ -0,0 +1,44 @@
+# Controller Interface Queues
+
+Controller Interface queues consist of:
+* Command queue
+  * The commands are fetched by the `hci` module from the `COMMAND_PORT`.
+* TX data queue
+  * Data is fetched by the `hci` module from the `XFER_DATA_PORT`.
+* RX data queue
+  * Data is put to the `XFER_DATA_PORT` by the `hci` module.
+* Response queue
+  * Responses are retrieved from `i3c_ctrl` and put to the `XFER_DATA_PORT` by the `hci` module.
+
+Controller Interface queues are depth-configurable with the [I3C Configuration](config.md#configuring-the-i3c-core).
+
+Queues generate several status indicators that will be used to trigger appropriate interrupts:
+  * `*_fifo_empty_` - no elements are enqueued in corresponding FIFO.
+  * `*_fifo_full_` - `*_FIFO_DEPTH` are enqueued in the corresponding FIFO.
+  * `*_fifo_apch_thld_` - the user-defined threshold has been reached. <!-- TODO: name will be changed -->
+
+## Queue threshold
+Command and response queue thresholds are controlled via [QUEUE_THLD_CTRL](https://github.com/chipsalliance/i3c-core-rdl/blob/4028ed29254aefdbe9c805e8bfaa275e200994ba/src/rdl/pio_registers.rdl#L44) register.
+RX and TX data queue thresholds are controlled via [DATA_BUFFER_THLD_CTRL](https://github.com/chipsalliance/i3c-core-rdl/blob/4028ed29254aefdbe9c805e8bfaa275e200994ba/src/rdl/pio_registers.rdl#L75).
+
+### Command queue threshold
+* The threshold for command queue is set by a write to the `QUEUE_THLD_CTRL` to the 8-bit `CMD_EMPTY_BUF_THLD` field.
+* The threshold `N` of range `<1, 255>` (inclusive) will cause an `CMD_QUEUE_READY_STAT` interrupt when there's `N` or more remaining empty entries left in the command queue.
+* If the `N` value is greater than the size of the command queue (`CMD_FIFO_DEPTH`) the full depth will be considered (the threshold will be set to `CMD_FIFO_DEPTH`).
+
+### Response  queue threshold
+* The threshold for response queue is set by a write to `QUEUE_THLD_CTRL` to the 8-bit `RESP_BUF_THLD` field.
+* The threshold `N` of range `<1, 255>` (inclusive) will cause an `RESP_READY_STAT` interrupt when there's `N` or more responses enqueued in the response queue.
+* If the `N` value is greater or equal than the size of the response queue (`RESP_FIFO_DEPTH`) the full depth will be considered (the threshold will be set to `RESP_FIFO_DEPTH - 1`)
+
+### TX queue threshold
+* The threshold for the TX queue is set by a write to `DATA_BUFFER_THLD_CTRL` to the 3-bit `TX_BUF_THLD` field.
+* The threshold `N` of range `<0, 7>` (inclusive) will trigger an `TX_THLD_STAT` interrupt when `2^(N+1)` (`2` to the power of `N+1`) `DWORD` empty entries are available in the TX queue.
+* The software must provide an `N` value that corresponds to the threshold less or equal than `TX_FIFO_DEPTH`, otherwise the `clog2(TX_FIFO_DEPTH) - 1` will be applied.
+
+### RX queue threshold
+* The threshold for the RX queue is set by a write to `DATA_BUFFER_THLD_CTRL` to the 3-bit `RX_BUF_THLD` field.
+* The threshold `N` of range `<0, 7>` (inclusive) will trigger an `RX_THLD_STAT` interrupt when `2^(N+1)` (`2` to the power of `N+1`) `DWORD` entries are enqueued in the RX queue.
+* The software must provide an `N` value that corresponds to the threshold less than `RX_FIFO_DEPTH`, otherwise the `clog2(RX_FIFO_DEPTH) - 2` will be applied.
+
+All queues utilize [caliptra_prim_fifo_sync.sv](https://github.com/chipsalliance/caliptra-rtl/blob/9c815c335a92901b27458271a885b2128e51e687/src/caliptra_prim/rtl/caliptra_prim_fifo_sync.sv#L9) fifo implementation.

docs/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'I3C Core - documentation'
+basic_filename = u'i3c-core--documentation'
+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)

docs/source/config.md

@@ -0,0 +1,7 @@
+# Configuring the I3C Core
+
+The I3C Core is configured with the [i3c_core_config](../../tools/i3c_config/i3c_core_config.py) python script, which reads configurations from the `i3c_core_configs.yaml` YAML file.
+
+The supported configurations can be found in [i3c_core_configs.yaml](../../i3c_core_configs.yaml) file.
+
+More details on the usage of the tool can be found in the [README](../../tools/i3c_config/README.md).

docs/source/dv.md

@@ -0,0 +1,8 @@
+# Design verification
+
+This chapter presents available models and tools, which are used for I3C verification.
+The core is verified with [the Cocotb/Verilator + unit tests](../../verification/block) and [the UVM test suite](../../verification/uvm_i3c/).
+
+## Verification plan
+
+The verification plan is [here](../../verification/uvm_i3c/testplan.hjson).