diff --git a/docs/.gitignore b/docs/.gitignore new file mode 100644 index 0000000..e587a9c --- /dev/null +++ b/docs/.gitignore @@ -0,0 +1,2 @@ +.venv +build diff --git a/docs/.readthedocs.yaml b/docs/.readthedocs.yaml new file mode 100644 index 0000000..aaa3306 --- /dev/null +++ b/docs/.readthedocs.yaml @@ -0,0 +1,13 @@ +version: 2 + +build: + os: ubuntu-22.04 + tools: + python: '3.11' + +sphinx: + configuration: source/conf.py + +python: + install: + - requirements: source/requirements.txt diff --git a/docs/Makefile b/docs/Makefile new file mode 100644 index 0000000..5f16c0e --- /dev/null +++ b/docs/Makefile @@ -0,0 +1,29 @@ +# Minimal makefile for Sphinx documentation +# + +# You can set these variables from the command line, and also +# from the environment for the first two. +SPHINXOPTS ?= +SPHINXBUILD ?= sphinx-build +SOURCEDIR = source +BUILDDIR = build +PYTHON ?= python3 + +# 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) + +clean: + @$(SPHINXBUILD) -M clean "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) + $(MAKE) -C clean + +.PHONY: reqs +reqs: + $(PYTHON) -m pip install -r source/requirements.txt diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 0000000..bdd299e --- /dev/null +++ b/docs/README.md @@ -0,0 +1,11 @@ +GateMate Architecture Documentation +=================================== + +Setting up environment +---------------------- + +``` +python -m venv .venv +source .venv/bin/activate +make reqs +``` diff --git a/docs/source/architecture/global.rst b/docs/source/architecture/global.rst new file mode 100644 index 0000000..dc8b6c0 --- /dev/null +++ b/docs/source/architecture/global.rst @@ -0,0 +1,2 @@ +Global Routing +=============== diff --git a/docs/source/architecture/overview.rst b/docs/source/architecture/overview.rst new file mode 100644 index 0000000..8094b7f --- /dev/null +++ b/docs/source/architecture/overview.rst @@ -0,0 +1,2 @@ +Overview +========= diff --git a/docs/source/architecture/routing.rst b/docs/source/architecture/routing.rst new file mode 100644 index 0000000..078173c --- /dev/null +++ b/docs/source/architecture/routing.rst @@ -0,0 +1,2 @@ +General Routing +================ diff --git a/docs/source/architecture/tiles.rst b/docs/source/architecture/tiles.rst new file mode 100644 index 0000000..315d8a5 --- /dev/null +++ b/docs/source/architecture/tiles.rst @@ -0,0 +1,2 @@ +Tiles +===== diff --git a/docs/source/bitstream/bitstream.rst b/docs/source/bitstream/bitstream.rst new file mode 100644 index 0000000..b84db99 --- /dev/null +++ b/docs/source/bitstream/bitstream.rst @@ -0,0 +1,119 @@ +Bitstream Format +================= + +Structure +---------- + +GateMate bitstreams consist of command blocks. There is no specific header to distinguish them from other files, but each one starts with the CMD_PATH command to set the first die on the chip. + +.. list-table:: + :widths: 20 20 10 35 15 + :header-rows: 1 + + * - Command + - Length + - CRC1 + - Data + - CRC2 + * - 1 byte + - 1 or 2 bytes + - 2 bytes + - n bytes + - 2 bytes + + +Each command byte is followed by data length, and that is one byte, except in the case of the CMD_FRAM command where we used two bytes in little endian format. +CRC following it, contains current (header only) CRC and is written in big endian format. CRC is calculated with the so-called CRC-16/ISO-HDLC or CRC-16/X-25 algorithm ( poly 0x1021, init 0xffff, xored output 0xffff). Number of data bytes following is defined in the header. Second CRC contains complete CRC for all previous bytes delivered in block (including header). Some commands require additional bytes after CRC and those are fixed valued, in some cases they are just NOP bytes (0x00), and some require “execute command byte” (0x33) surrounded by multiple NOPs. + + +Command list +------------------ + +.. list-table:: + :widths: 25 5 7 63 + :header-rows: 1 + + * - Command + - Hex + - Len Size + - Description + * - **CMD_PLL** + - C1 + - 1 + - PLL configuration + * - **CMD_CFGMODE** + - C2 + - 1 + - Change configuration mode + * - **CMD_CFGRST** + - C3 + - 1 + - Reset all configuration latches + * - **CMD_FLASH** + - C5 + - 1 + - SPI flash access + * - **CMD_DLXP** + - C6 + - 1 + - Latch configuration X pattern + * - **CMD_DLYP** + - C7 + - 1 + - Latch configuration Y pattern + * - **CMD_LXLYS** + - C8 + - 1 + - Latch configuration X,Y location + * - **CMD_ACLCU** + - C9 + - 1 + - Address counter + * - **CMD_DLCU** + - CA + - 1 + - Configuration data + * - **CMD_DRXP** + - CC + - 1 + - RAM configuration X pattern + * - **CMD_RXRYS** + - CE + - 1 + - RAM configuration X,Y location + * - **CMD_FRAM** + - D2 + - 2 + - Block ram fill data + * - **CMD_SERDES** + - D7 + - 1 + - Serdes configuration + * - **CMD_D2D** + - D8 + - 1 + - Enable/disable die-to-die direction + * - **CMD_PATH** + - D9 + - 1 + - Enable forwarding configuration to die + * - **CMD_JUMP** + - DA + - 1 + - Jump to address in configuration + * - **CMD_CHG_STATUS** + - DB + - 1 + - FPGA configuration change + * - **CMD_WAIT_PLL** + - DC + - 1 + - Wait for PLL lock + * - **CMD_SPLL** + - DD + - 1 + - Select PLLs + * - **CMD_SLAVE_MODE** + - DE + - 1 + - Set SPI slave mode diff --git a/docs/source/bitstream/commands.rst b/docs/source/bitstream/commands.rst new file mode 100644 index 0000000..bbc9b96 --- /dev/null +++ b/docs/source/bitstream/commands.rst @@ -0,0 +1,130 @@ +Bitstream Commands +=================== + +CMD_PATH +--------- +To be able to specify die to program it is required to properly forward JTAG to specific +direction and set mode accordingly. To program first die we use 0x10 value for this command +and it first one to be executed. + +.. list-table:: + :widths: 10 40 + :header-rows: 1 + + * - Bit + - Description + * - 0 + - Reset to default state + * - 1 + - Set to path to top + * - 2 + - Set to path to right + * - 3 + - Enable forwarding mode + * - 4 + - Enable programming mode + +.. warning:: + This command have data after payload, and it consists of 9 bytes ``0x00 0x00 0x00 0x00 0x33 0x00 0x00 0x00 0x00`` and + it is used to execute this JTAG command. + + +CMD_LXLYS +---------- +Before sending any configuration data it is required to specify location of a specific TILE, and for latch configuration that configures all +logic and IO blocks it is this command. + +.. list-table:: + :widths: 10 10 40 + :header-rows: 1 + + * - Byte + - Range + - Description + * - 0 + - 0..81 + - X location (column) + * - 1 + - 0..65 + - Y location (row) + +CMD_DLXP +--------- +Alternate way of setting location for configuration data is by setting pattern for both column and row. + +This commands sets row pattern and each bit represent one of the rows. There are total of 9 bytes used in payload. + +CMD_DLYP +--------- +This commands sets column pattern and each bit represent one of the columns. There are total of 11 bytes used in payload. + +CMD_DLCU +--------- +After location is set with one of previous commands, it is required to set a data payload. + +For configuring logic and IO tiles data payload is 112 bytes max. Payload can be smaller, but programming +will act as it is zero padded till full size. +This command is also used to configure RAM blocks, there we expect 27 bytes of payload maximum. + +CMD_RXRYS +---------- +Similar to **CMD_LXLYS** command, there is a command to specify RAM block to program. + +.. list-table:: + :widths: 10 10 40 + :header-rows: 1 + + * - Byte + - Range + - Description + * - 0 + - 0..3 + - X location (column) + * - 1 + - 0..7 + - Y location (row) + +CMD_DRXP +--------- +As alternative to **CMD_RXRYS** command we can use this one to specify a pattern, note that +each bit of one byte payload is used to set one of 4 columns. + +CMD_CFGRST +----------- +Resets all configuration latches to value of a byte from payload. + +CMD_PLL +-------- + +CMD_CFGMODE +------------ + +CMD_FLASH +---------- + +CMD_ACLCU +---------- + +CMD_FRAM +--------- + +CMD_SERDES +----------- + +CMD_D2D +-------- + +CMD_JUMP +-------- + +CMD_CHG_STATUS +--------------- + +CMD_WAIT_PLL +------------- + +CMD_SPLL +--------- + +CMD_SLAVE_MODE +--------------- diff --git a/docs/source/conf.py b/docs/source/conf.py new file mode 100644 index 0000000..9201aa8 --- /dev/null +++ b/docs/source/conf.py @@ -0,0 +1,34 @@ +# Configuration file for the Sphinx documentation builder. +# +# For the full list of built-in configuration values, see the documentation: +# https://www.sphinx-doc.org/en/master/usage/configuration.html + +# -- Project information ----------------------------------------------------- +# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information + +project = 'Project Peppercorn' +copyright = '2024, YosysHQ' +author = 'YosysHQ' + +# -- General configuration --------------------------------------------------- +# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration + +extensions = ['sphinx_rtd_theme'] + +templates_path = ['_templates'] +exclude_patterns = [] + + + +# -- Options for HTML output ------------------------------------------------- +# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output + +html_theme = 'sphinx_rtd_theme' +html_theme_options = { + "collapse_navigation": True, + "sticky_navigation": True, + "includehidden": True, + "navigation_depth": 4, + "titles_only": False +} +html_static_path = ['_static'] diff --git a/docs/source/index.rst b/docs/source/index.rst new file mode 100644 index 0000000..10cd5c0 --- /dev/null +++ b/docs/source/index.rst @@ -0,0 +1,18 @@ +Welcome to Project Peppercorn +============================== + +.. toctree:: + :maxdepth: 2 + :caption: Architecture + + architecture/overview.rst + architecture/tiles.rst + architecture/routing.rst + architecture/global.rst + +.. toctree:: + :maxdepth: 2 + :caption: Bitstream + + bitstream/bitstream.rst + bitstream/commands.rst diff --git a/docs/source/requirements.txt b/docs/source/requirements.txt new file mode 100644 index 0000000..f2db166 --- /dev/null +++ b/docs/source/requirements.txt @@ -0,0 +1,2 @@ +sphinx +sphinx_rtd_theme