Add user documentation

.gitattributes

@@ -16,4 +16,3 @@
 
 # Jupyter notebook
 *.ipynb  text eol=lf
-

.gitignore

@@ -19,4 +19,3 @@ __pycache__/
 
 docs/_build
 .cache
-

chipflow_lib/software/drivers/spi.c

@@ -2,7 +2,7 @@
 #include "spi.h"
 
 void spi_init(volatile spi_regs_t *spi, uint32_t divider) {
-	spi->divider = divider;
+    spi->divider = divider;
     spi->config = 0x02; // CS=0, SCK_EDGE=1, SCK_IDLE=0
 }
 
@@ -11,8 +11,8 @@ uint32_t spi_xfer(volatile spi_regs_t *spi, uint32_t data, uint32_t width, bool
     spi->send_data = data << (32U - width);
     while (!(spi->status & 0x1)) // wait for rx full
         ;
-   	if (deselect) {
-    	spi->config = ((width - 1) << 3) | 0x02; // CS=0, SCK_EDGE=1, SCK_IDLE=0
+    if (deselect) {
+        spi->config = ((width - 1) << 3) | 0x02; // CS=0, SCK_EDGE=1, SCK_IDLE=0
     }
     return spi->receive_data;
 }

chipflow_lib/software/drivers/spiflash.S

@@ -14,7 +14,7 @@ mv t3, ra
 # address of SPI ctrl reg
 li   a0, 0xb0000000
 # enter bypass mode
-lbu   t1, 0(a0) 
+lbu   t1, 0(a0)
 ori   t1, t1, 0x1
 sb    t1, 0(a0)
 call flashio_wait_bypass_ready
@@ -40,7 +40,7 @@ j flashio_xfer
 
 flashio_done:
 # exit bypass mode
-lbu   t1, 0(a0) 
+lbu   t1, 0(a0)
 andi   t1, t1, 0xFE
 sb    t1, 0(a0)
 

chipflow_lib/software/drivers/spiflash.c

@@ -39,7 +39,7 @@ bool spiflash_is_winbond(volatile spiflash_regs_t *flash) {
 	if ((id & 0x00ff0000) == WINBOND_ID<<16) return true;
 	else return false;
 }
-	
+
 void spiflash_set_qspi_flag(volatile spiflash_regs_t *flash) {
 	uint8_t buffer[8];
 

chipflow_lib/steps/__init__.py

@@ -0,0 +1,17 @@
+"""
+Steps provide an extensible way to modify the `chipflow` command behavior for a given design
+"""
+
+from abc import ABC
+
+class StepBase(ABC):
+    def __init__(self, config={}):
+        ...
+
+    def build_cli_parser(self, parser):
+        "Build the cli parser for this step"
+        ...
+
+    def run_cli(self, args):
+        "Called when this step's is used from `chipflow` command"
+        self.build()

chipflow_lib/steps/board.py

@@ -1,6 +1,7 @@
 # SPDX-License-Identifier: BSD-2-Clause
+from . import StepBase
 
-class BoardStep:
+class BoardStep(StepBase):
     """Build the design for a board."""
 
     def __init__(self, config, platform):
@@ -13,4 +14,5 @@ def run_cli(self, args):
         self.build()
 
     def build(self):
+        "Build for the given platform"
         self.platform.build()

chipflow_lib/steps/silicon.py

@@ -13,14 +13,15 @@
 import dotenv
 from amaranth import *
 
+from . import StepBase
 from .. import ChipFlowError
 from ..platforms import SiliconPlatform, top_interfaces, load_pinlock
 
 
 logger = logging.getLogger(__name__)
 
 
-class SiliconTop(Elaboratable):
+class SiliconTop(StepBase, Elaboratable):
     def __init__(self, config={}):
         self._config = config
 
@@ -53,7 +54,7 @@ def elaborate(self, platform: SiliconPlatform):
 
 
 class SiliconStep:
-    """Prepare and submit the design for an ASIC."""
+    """Step to Prepare and submit the design for an ASIC."""
     def __init__(self, config):
         self.config = config
 

chipflow_lib/steps/sim.py

@@ -3,8 +3,9 @@
 from doit.cmd_base import ModuleTaskLoader
 from doit.doit_cmd import DoitMain
 
+from . import StepBase
 
-class SimStep:
+class SimStep(StepBase):
     """Simulate the design."""
 
     doit_build_module = None

chipflow_lib/steps/software.py

@@ -3,9 +3,10 @@
 from doit.cmd_base import ModuleTaskLoader
 from doit.doit_cmd import DoitMain
 
+from . import StepBase
 
-class SoftwareStep:
-    """Build the software."""
+class SoftwareStep(StepBase):
+    """Base step to build the software."""
 
     doit_build_module = None
 
@@ -19,7 +20,9 @@ def run_cli(self, args):
         self.build()
 
     def doit_build(self):
+        "Run the overridden doit_build_module"
         DoitMain(ModuleTaskLoader(self.doit_build_module)).run(["build_software"])
 
     def build(self):
+        "Build the software for your design"
         self.doit_build()

docs/_templates/autoapi/class.rst

@@ -0,0 +1,23 @@
+{% if visible_methods or visible_attributes %}
+.. rubric:: Overview
+
+{% set summary_methods = visible_methods|rejectattr("properties", "contains", "property")|list %}
+{% set summary_attributes = visible_attributes + visible_methods|selectattr("properties", "contains", "property")|list %}
+
+{% if summary_attributes %}
+{{ macros.auto_summary(summary_attributes, title="Attributes")|indent(3) }}
+{% endif %}
+
+{% if summary_methods %}
+{{ macros.auto_summary(summary_methods, title="Methods")|indent(3) }}
+{% endif %}
+
+.. rubric:: Members
+
+{% for attribute in visible_attributes %}
+{{ attribute.render()|indent(3) }}
+{% endfor %}
+{% for method in visible_methods %}
+{{ method.render()|indent(3) }}
+{% endfor %}
+{% endif %}

docs/_templates/autoapi/macros.rst

@@ -0,0 +1,43 @@
+{% macro _render_item_name(obj, sig=False) -%}
+:py:obj:`{{ obj.name }} <{{ obj.id }}>`
+{%- if sig -%}
+\ (
+{%- for arg in obj.obj.args -%}
+{%- if arg[0] %}{{ arg[0]|replace('*', '\*') }}{% endif -%}{{  arg[1] -}}
+{%- if not loop.last  %}, {% endif -%}
+{%- endfor -%}
+){%- endif -%}
+{%- endmacro %}
+
+{% macro _item(obj, sig=False, label='') %}
+   * - {{ _render_item_name(obj, sig) }}
+     - {% if label %}:summarylabel:`{{ label }}` {% endif %}{% if obj.summary %}{{ obj.summary }}{% else %}\-{% endif +%}
+
+{% endmacro %}
+
+{% macro auto_summary(objs, title='') -%}
+.. list-table:: {{ title }}
+
+   :header-rows: 0
+   :widths: auto
+   :class: summarytable
+
+   {% for obj in objs -%}
+   {%- set sig = (obj.type in ['method', 'function'] and not 'property' in obj.properties) -%}
+
+   {%- if 'property' in obj.properties -%}
+   {%- set label = 'prop' -%}
+   {%- elif 'classmethod' in obj.properties -%}
+   {%- set label = 'class' -%}
+   {%- elif 'abstractmethod' in obj.properties -%}
+   {%- set label = 'abc' -%}
+   {%- elif 'staticmethod' in obj.properties -%}
+   {%- set label = 'static' -%}
+   {%- else -%}
+   {%- set label = '' -%}
+   {%- endif -%}
+
+   {{- _item(obj, sig=sig, label=label) -}}
+   {%- endfor -%}
+
+{% endmacro %}

docs/_templates/autoapi/module.rst

@@ -0,0 +1,19 @@
+{% if "show-module-summary" in autoapi_options and (visible_classes or visible_functions) %}
+{% block classes scoped %}
+{% if visible_classes %}
+{{ macros.auto_summary(visible_classes, title="Classes") }}
+{% endif %}
+{% endblock %}
+
+{% block functions scoped %}
+{% if visible_functions %}
+{{ macros.auto_summary(visible_functions, title="Functions") }}
+{% endif %}
+{% endblock %}
+
+{% block attributes scoped %}
+{% if visible_attributes %}
+{{ macros.auto_summary(visible_attributes, title="Attributes") }}
+{% endif %}
+{% endblock %}
+{% endif %}

docs/chipflow-commands.rst

@@ -41,4 +41,3 @@ A default simulation driver (the C++ code that runs the simulation) is included
 ---------------------
 
 If the design contains a CPU, the ``chipflow software build`` command is used to build test firmware for the target CPU. Which C source files to include, and any build options (like the target architecture or enabled RISC-V extensions) can be customised in the ``software/doit_build.py`` doit build script inside the user project.
-

docs/chipflow-toml-guide.rst

@@ -11,7 +11,7 @@ Let's start with a typical example:
 .. testcode::
    :hide:
 
-   # Assert that example-chipflow.toml matches the current config schema. If 
+   # Assert that example-chipflow.toml matches the current config schema. If
    # this test fails, then its likely that the content in this file will need
    # to be updated.
    from chipflow_lib import _parse_config_file
@@ -178,5 +178,3 @@ Note that in this context, the :term:type parameter can only be ``ground`` or ``
 This is a work in progress, and currently you can use the defaults provided by customer support.
 
 .. _Caravel Harness: https://caravel-harness.readthedocs.io/en/latest/
-
-

docs/conf.py

@@ -37,8 +37,18 @@
 ]
 
 html_theme = 'furo'
-html_logo = '_static/chipflow-logo.svg'
+html_logo = '_assets/chipflow-logo.svg'
 html_title = "ChipFlow Platform Documentation"
+html_static_path = ['_assets']
+
+html_theme_options = {
+    "dark_css_variables": {
+        "admonition-font-size": "0.9 rem",
+    },
+    "light_css_variables": {
+        "admonition-font-size": "0.9 rem",
+    },
+}
 
 autodoc_typehints = 'description'
 
@@ -57,8 +67,11 @@
     'imported-members',
 ]
 
-# Exclude autoapi templates
-exclude_patterns = [autoapi_template_dir]
+# Exclude autoapi templates and in-progress stuff
+exclude_patterns = [
+    autoapi_template_dir,
+    "unfinished",
+]
 
 intersphinx_mapping = {
     'py': ('https://docs.python.org/3/', None),