i2c-gpio-expander: Add Basic Documentation

.github/workflows/drc.yml

@@ -30,7 +30,7 @@ on:
 
 jobs:
     drc:
-        runs-on: ubuntu-latest
+        runs-on: ubuntu-22.04
         steps:
             -   name: Get all files
                 uses: actions/checkout@master

i2c-gpio-expander/doc/.gitignore

@@ -0,0 +1,2 @@
+build*
+venv/

i2c-gpio-expander/doc/Makefile

@@ -0,0 +1,39 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS     ?= -j auto -w build.log
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = source
+BUILDDIR      = build
+
+.DEFAULT_GOAL := docs
+
+#docs: clean setup build display
+docs: clean  build display
+
+
+.ONESHELL:
+clean:
+	@rm -rf $(BUILDDIR)
+	@rm -rf build.log
+
+build:
+	@$(SPHINXBUILD) -M "html" "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+# 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)
+
+
+.ONESHELL:
+display:
+	@cd $(BUILDDIR)/html
+	@xdg-open index.html

i2c-gpio-expander/doc/README.rst

@@ -0,0 +1,22 @@
+Documentation
+=============
+
+* Create a virtual environment::
+
+    virtualenv -p python3.12 venv
+
+* Source the virtual environment::
+
+    source venv/bin/activate
+
+* Install all required packages::
+
+    pip install -r requirements.txt
+
+* Build the documentation::
+
+    make html
+
+* Open the documentation::
+
+     firefox build/html/index.html

i2c-gpio-expander/doc/requirements-packages.txt

@@ -0,0 +1,3 @@
+restructuredtext-lint
+sphinx
+sphinx-rtd-theme

i2c-gpio-expander/doc/requirements.txt

@@ -0,0 +1,23 @@
+alabaster==1.0.0
+babel==2.16.0
+certifi==2024.12.14
+charset-normalizer==3.4.1
+docutils==0.21.2
+idna==3.10
+imagesize==1.4.1
+Jinja2==3.1.5
+MarkupSafe==3.0.2
+packaging==24.2
+Pygments==2.19.1
+requests==2.32.3
+snowballstemmer==2.2.0
+Sphinx==8.1.3
+sphinx-rtd-theme==3.0.2
+sphinxcontrib-applehelp==2.0.0
+sphinxcontrib-devhelp==2.0.0
+sphinxcontrib-htmlhelp==2.1.0
+sphinxcontrib-jquery==4.1
+sphinxcontrib-jsmath==1.0.1
+sphinxcontrib-qthelp==2.0.0
+sphinxcontrib-serializinghtml==2.0.0
+urllib3==2.3.0

i2c-gpio-expander/doc/source/conf.py

@@ -0,0 +1,35 @@
+# Configuration file for the Sphinx documentation builder.
+
+# -- Project information
+
+project = 'I2C GPIO Expander'
+copyright = '2024, IHP Open PDK'
+author = 'Daniel Schultz'
+
+release = '0.1'
+version = '0.1.0'
+
+# -- General configuration
+
+extensions = [
+    'sphinx.ext.duration',
+    'sphinx.ext.doctest',
+    'sphinx.ext.autodoc',
+    'sphinx.ext.autosummary',
+    'sphinx.ext.intersphinx',
+]
+
+intersphinx_mapping = {
+    'python': ('https://docs.python.org/3/', None),
+    'sphinx': ('https://www.sphinx-doc.org/en/master/', None),
+}
+intersphinx_disabled_domains = ['std']
+
+templates_path = ['_templates']
+
+# -- Options for HTML output
+
+html_theme = 'sphinx_rtd_theme'
+
+# -- Options for EPUB output
+epub_show_urls = 'footnote'

i2c-gpio-expander/doc/source/design.rst

@@ -0,0 +1,32 @@
+Design
+======
+
+Miscellaneous
+-------------
+
+The entire chip core is a synchronous design operating at 50 MHz. This clock must be supplied via an external oscillator connected to the clock pin. The design also requires an active-low reset signal, which must be externally provided. It is recommended to hold the reset signal low for at least 1 µs until the core voltage stabilizes. This ensures proper initialization of all registers and correct latching of the external address.
+
+Communication
+-------------
+
+The chip features an I2C interface for receiving and handling transmissions from an external I2C controller. Additionally, it includes an interrupt pin to notify the controller of any pending interrupts on one of the GPIO pins.
+
+This device supports ``I2C Fast Mode``, enabling communication speeds of up to 400 kbit/s.
+
+GPIO
+----
+
+The device is equipped with 8 General Purpose Input/Output (GPIO) pins, configurable through the I2C interface.
+
++----------+-----------+--------+----------------------+
+| Register | Name      | Access | Description          |
++==========+===========+========+======================+
+| 0x0      | Value     | R      | Returns IO value     |
++----------+-----------+--------+----------------------+
+| 0x1      | Write     | R/W    | Writes output value  |
++----------+-----------+--------+----------------------+
+| 0x2      | Direction | R/W    | Enables output value |
++----------+-----------+--------+----------------------+
+
+.. note::
+   The interrupt registers are currently missing and will be added later.

i2c-gpio-expander/doc/source/index.rst

@@ -0,0 +1,20 @@
+End-to-end Open-Source I2C GPIO Expander
+========================================
+
+Welcome to the documentation for the end-to-end Open-Source I2C GPIO Expander!
+
+.. image:: _static/i2c-gpio-expander-overview.webp
+    :align: center
+    :alt: I2C GPIO Expander Overview
+    :width: 300
+
+This guide is organized into the following chapters:
+
+.. toctree::
+   :maxdepth: 1
+
+   design.rst
+   pinout.rst
+   known-issues.rst
+
+

i2c-gpio-expander/doc/source/known-issues.rst

@@ -0,0 +1,4 @@
+Known Issues
+============
+
+* The design includes twice the number of VDD and VSS pads but lacks IOVSS and IOVDD pads.

i2c-gpio-expander/doc/source/pinout.rst

@@ -0,0 +1,121 @@
+Chip Pin-Out
+============
+
+The image below highlights the location of pin 1 on the chip.
+
+.. image:: _static/i2c-gpio-expander-pin1.webp
+    :align: center
+    :alt: I2C GPIO Expander Pin-Out
+    :width: 400
+
+
+The table that follows provides a detailed explanation of each I/O pin's function.
+
+.. list-table:: Pin-Out
+   :stub-columns: 1
+
+   * - Pin
+     - Position
+     - Name
+     - IO
+     - Function
+   * - 1
+     - East
+     - VDD
+     -
+     - Ground
+   * - 2
+     - East
+     - VSS
+     -
+     - 1.1V
+   * - 3
+     - East
+     - io_address_0
+     - I
+     - I2C Device address bit 0.
+   * - 4
+     - East
+     - io_address_1
+     - I
+     - I2C Device address bit 1.
+   * - 5
+     - East
+     - io_address_2
+     - I
+     - I2C Device address bit 2.
+   * - 6
+     - South
+     - io_clock
+     - I
+     - 50 MHz input clock.
+   * - 7
+     - South
+     - io_reset
+     - I
+     - Active-low reset signal.
+   * - 8
+     - South
+     - io_i2c_scl
+     - IO
+     - I2C Open-Drain SCL signal. Requires external pull-ups.
+   * - 9
+     - South
+     - io_i2c_sda
+     - IO
+     - I2C Open-Drain SDA signal. Requires external pull-ups.
+   * - 10
+     - South
+     - io_i2c_interrupt
+     - O
+     - I2C interrupt to external controller.
+   * - 11
+     - West
+     - io_gpio_5
+     - IO
+     - GPIO Pin 5
+   * - 12
+     - West
+     - io_gpio_6
+     - IO
+     - GPIO Pin 6
+   * - 13
+     - West
+     - io_gpio_7
+     - IO
+     - GPIO Pin 7
+   * - 14
+     - West
+     - VSS
+     -
+     - Ground
+   * - 15
+     - West
+     - VDD
+     -
+     - 1.1V
+   * - 16
+     - North
+     - io_gpio_0
+     - IO
+     - GPIO Pin 0
+   * - 17
+     - North
+     - io_gpio_1
+     - IO
+     - GPIO Pin 1
+   * - 18
+     - North
+     - io_gpio_2
+     - IO
+     - GPIO Pin 2
+   * - 19
+     - North
+     - io_gpio_3
+     - IO
+     - GPIO Pin 3
+   * - 20
+     - North
+     - io_gpio_4
+     - IO
+     - GPIO Pin 4