diff --git a/.github/workflows/drc.yml b/.github/workflows/drc.yml index 10e9863..1fb437f 100644 --- a/.github/workflows/drc.yml +++ b/.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 diff --git a/i2c-gpio-expander/doc/.gitignore b/i2c-gpio-expander/doc/.gitignore new file mode 100644 index 0000000..8323105 --- /dev/null +++ b/i2c-gpio-expander/doc/.gitignore @@ -0,0 +1,2 @@ +build* +venv/ diff --git a/i2c-gpio-expander/doc/Makefile b/i2c-gpio-expander/doc/Makefile new file mode 100644 index 0000000..71aeac3 --- /dev/null +++ b/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 diff --git a/i2c-gpio-expander/doc/README.rst b/i2c-gpio-expander/doc/README.rst new file mode 100644 index 0000000..725a0c9 --- /dev/null +++ b/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 diff --git a/i2c-gpio-expander/doc/requirements-packages.txt b/i2c-gpio-expander/doc/requirements-packages.txt new file mode 100644 index 0000000..f1ce91d --- /dev/null +++ b/i2c-gpio-expander/doc/requirements-packages.txt @@ -0,0 +1,3 @@ +restructuredtext-lint +sphinx +sphinx-rtd-theme diff --git a/i2c-gpio-expander/doc/requirements.txt b/i2c-gpio-expander/doc/requirements.txt new file mode 100644 index 0000000..f314e06 --- /dev/null +++ b/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 diff --git a/i2c-gpio-expander/doc/source/_static/IHP_logo.png b/i2c-gpio-expander/doc/source/_static/IHP_logo.png new file mode 100644 index 0000000..67d28f8 Binary files /dev/null and b/i2c-gpio-expander/doc/source/_static/IHP_logo.png differ diff --git a/i2c-gpio-expander/doc/source/_static/i2c-gpio-expander-overview.webp b/i2c-gpio-expander/doc/source/_static/i2c-gpio-expander-overview.webp new file mode 100644 index 0000000..775538a Binary files /dev/null and b/i2c-gpio-expander/doc/source/_static/i2c-gpio-expander-overview.webp differ diff --git a/i2c-gpio-expander/doc/source/_static/i2c-gpio-expander-pin1.webp b/i2c-gpio-expander/doc/source/_static/i2c-gpio-expander-pin1.webp new file mode 100644 index 0000000..5c13e71 Binary files /dev/null and b/i2c-gpio-expander/doc/source/_static/i2c-gpio-expander-pin1.webp differ diff --git a/i2c-gpio-expander/doc/source/conf.py b/i2c-gpio-expander/doc/source/conf.py new file mode 100644 index 0000000..7720ab7 --- /dev/null +++ b/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' diff --git a/i2c-gpio-expander/doc/source/design.rst b/i2c-gpio-expander/doc/source/design.rst new file mode 100644 index 0000000..af18e3d --- /dev/null +++ b/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. diff --git a/i2c-gpio-expander/doc/source/index.rst b/i2c-gpio-expander/doc/source/index.rst new file mode 100644 index 0000000..33f0bfa --- /dev/null +++ b/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 + + diff --git a/i2c-gpio-expander/doc/source/known-issues.rst b/i2c-gpio-expander/doc/source/known-issues.rst new file mode 100644 index 0000000..1c1b0e5 --- /dev/null +++ b/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. diff --git a/i2c-gpio-expander/doc/source/pinout.rst b/i2c-gpio-expander/doc/source/pinout.rst new file mode 100644 index 0000000..858694f --- /dev/null +++ b/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