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..96ef68f --- /dev/null +++ b/docs/Makefile @@ -0,0 +1,30 @@ +# 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) + +.PHONY: clean + +clean: + @$(SPHINXBUILD) -M clean "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) + +.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..853712b --- /dev/null +++ b/docs/README.md @@ -0,0 +1,11 @@ +Project Icestorm Documentation +=================================== + +Setting up environment +---------------------- + +``` +python -m venv .venv +source .venv/bin/activate +make reqs +``` diff --git a/docs/format.html b/docs/format.html deleted file mode 100644 index ee7a655..0000000 --- a/docs/format.html +++ /dev/null @@ -1,170 +0,0 @@ - - - -Project IceStorm – Bitstream File Format Documentation - -

Project IceStorm – Bitstream File Format Documentation

- -

-Project IceStorm aims at documenting the bitstream format of Lattice iCE40 -FPGAs and providing simple tools for analyzing and creating bitstream files. -This is work in progress. -

- -

General Description of the File Format

- -

-The bitstream file starts with the bytes 0xFF 0x00, followed by a sequence of -zero-terminated comment strings, followed by 0x00 0xFF. However, there seems to be -a bug in the Lattice "bitstream" tool that moves the terminating 0x00 0xFF a few -bytes into the comment string in some cases. -

- -

-After the comment sections the token 0x7EAA997E (MSB first) starts the actual -bit stream. The bitstream consists of one-byte commands, followed by a payload -word, followed by an optional block of data. The MSB nibble of the command byte -is the command opcode, the LSB nibble is the length of the command payload in -bytes. The commands that do not require a payload are using the opcode 0, with -the command encoded in the payload field. Note that this "payload" in this -context refers to a single integer argument, not the blocks of data that -follows the command in case of the CRAM and BRAM commands. -

- -

-The following commands are known: -

- - - - - - - - - - - - -
OpcodeDescription
0payload=1: Write CRAM Data
- payload=2: Read BRAM Data
- payload=3: Write BRAM Data
- payload=4: Read BRAM Data
- payload=5: Reset CRC
- payload=6: Wakeup
- payload=8: Reboot
1Set bank number
2CRC check
4Set boot address
5Set internal oscillator frequency range
- payload=0: low
- payload=1: medium
- payload=2: high
6Set bank width (16-bits, MSB first)
7Set bank height (16-bits, MSB first)
8Set bank offset (16-bits, MSB first)
9payload=0: Disable warm boot
- payload=16: Enable cold boot
- payload=32: Enable warm boot
- -

-Use iceunpack -vv to display the commands as they are interpreted by the tool. -

- -

-Note: The format itself seems to be very flexible. At the moment it is unclear what the FPGA -devices will do when presented with a bitstream that use the commands in a different way -than the bitstreams generated by the lattice tools. -

- -

Writing SRAM content

- -

-Most bytes in the bitstream are SRAM data bytes that should be written to the various SRAM banks -in the FPGA. The following sequence is used to program an SRAM cell: -

- - - -

-The bank width and height parameters reflect the width and height of the SRAM bank. A large SRAM can -be written in smaller chunks. In this case height parameter may be smaller and the offset parameter -reflects the vertical start position. -

- -

-There are four CRAM and four BRAM banks in an iCE40 FPGA. The different devices from the family -use different widths and heights, but the same number of banks. -

- -

-The CRAM banks hold the configuration bits for the FPGA fabric and hard IP blocks, the BRAM -corresponds to the contents of the block ram resources. -

- -

-The ordering of the data bits is in MSB first row-major order. -

- -

Organization of the CRAM

- -

Mapping of tile config bits to 2D CRAM

- -

-The chip is organized into four quadrants. Each CRAM memory bank contains the configuration bits for one quadrant. -The address 0 is always the corner of the quadrant, i.e. in one quadrant the bit addresses increase with the tile x/y -coordinates, in another they increase with the tile x coordinate but decrease with the tile y coordinate, and so on. -

- -

-For an iCE40 1k device, that has 12 x 16 tiles (not counting the io tiles), the CRAM bank 0 is the one containing the corner tile (1 1), -the CRAM bank 1 contains the corner tile (1 16), the CRAM bank 2 contains the corner tile (12 1) and the CRAM bank 3 contains the -corner tile (12 16). The entire CRAM of such a device is depicted on the right (bank 0 is in the lower left corner in blue/green). -

- -

-The checkerboard pattern in the picture visualizes which bits are associated -with which tile. The height of the configuration block is 16 for all tile -types, but the width is different for each tile type. IO tiles have -configurations that are 18 bits wide, LOGIC tiles are 54 bits wide, and -RAM tiles are 42 bits wide. (Notice the two slightly smaller columns for the RAM tiles.) -

- -

-The IO tiles on the top and bottom of the chip use a strange permutation pattern for their bits. It can be seen in the picture that -their columns are spread out horizontally. What cannot be seen in the picture is the columns also are not in order and the bit -positions are vertically permuted as well. The CramIndexConverter class in icepack.cc encapsulates the calculations -that are necessary to convert between tile-relative bit addresses and CRAM bank-relative bit addresses. -

- -

-The black pixels in the image correspond to CRAM bits that are not associated with any IO, LOGIC or RAM tile. -Some of them are unused, others are used by hard IPs or other global resources. The iceunpack tool reports -such bits, when set, with the ".extra_bit bank x y" statement in the ASCII output format. -

- -

Organization of the BRAM

- -

-This part of the documentation has not been written yet. -

- -

CRC Check

- -

-The CRC is a 16 bit CRC. The (truncated) polynomial is 0x1021 (CRC-16-CCITT). The "Reset CRC" command sets -the CRC to 0xFFFF. No zero padding is performed. -

- - diff --git a/docs/index.html b/docs/index.html deleted file mode 100644 index 9f6b6eb..0000000 --- a/docs/index.html +++ /dev/null @@ -1,590 +0,0 @@ - - - -Project IceStorm - -

Project IceStorm

- -

-2018-01-30: Released support for iCE40 UltraPlus devices.
-2017-03-13: Released support for LP384 chips (in all package variants).
-2016-02-07: Support for all package variants of LP1K, LP4K, LP8K and HX1K, HX4K, and HX8K.
-2016-01-17: First release of IceTime timing analysis. Video: https://youtu.be/IG5CpFJRnOk
-2015-12-27: Presentation of the IceStorm flow at 32C3 (Video on Youtube).
-2015-07-19: Released support for 8k chips. Moved IceStorm source code to GitHub.
-2015-05-27: We have a working fully Open Source flow with Yosys and Arachne-pnr! Video: http://youtu.be/yUiNlmvVOq8
-2015-04-13: Complete rewrite of IceUnpack, added IcePack, some major documentation updates
-2015-03-22: First public release and short YouTube video demonstrating our work: http://youtu.be/u1ZHcSNDQMM -

- -

What is Project IceStorm?

- -

-Project IceStorm aims at documenting the bitstream -format of Lattice iCE40 FPGAs and providing simple tools for analyzing and -creating bitstream files. The IceStorm flow (Yosys, Arachne-pnr, and IceStorm) is a -fully open source Verilog-to-Bitstream flow for iCE40 FPGAs. -

- -

-The focus of the project is on the iCE40 LP/HX 1K/4K/8K chips. (Most of the -work was done on HX1K-TQ144 and HX8K-CT256 parts.) The iCE40 UltraPlus parts -are also supported, including DSPs, oscillators, RGB and SPRAM. iCE40 LM, Ultra -and UltraLite parts are not yet supported. -

- -

Why the Lattice iCE40?

- -

-It has a very minimalistic architecture with a very regular structure. There are not many -different kinds of tiles or special function units. This makes it both ideal for creating -bitstream documentations and as a reference platform for general purpose FPGA tool development. -

- -

-Also, with the Lattice iCEstick there is -a cheap and easy to use development platform available, which makes the part interesting -for all kinds of projects. (The iCEstick features an HX1K device. Lattice also sells an iCE40-HX8K -Breakout Board featuring an HX8K chip.) -

- -

What is the Status of the Project?

- -

-We are pretty confident that we have the 1K and 8K devices completely -documented. For example, it seems we can create correct functional Verilog -models for all bitstreams generated by Lattice iCEcube2 for the iCE40 -HX1K-TQ144 and the iCE40 HX8K-CT256 using our icebox_vlog tool. -

- -

-Here is a list of currently supported parts and the corresponding options for arachne-pnr (place and route) and icetime (timing analysis): -

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
PartPackagePin SpacingI/Osnextpnr optsarachne-pnr optsicetime opts
iCE40-LP1K-SWG16TR16-ball WLCSP (1.40 x 1.48 mm)0.35 mm10--lp1k --package swg16tr-d 1k -P swg16tr-d lp1k
iCE40-UP3K-UWG3030-ball WLCSP (2.15 x 2.55 mm)0.40 mm21--up5k --package uwg30-d 5k -P uwg30-d up5k
iCE40-UP5K-UWG3030-ball WLCSP (2.15 x 2.55 mm)0.40 mm21--up5k --package uwg30-d 5k -P uwg30-d up5k
iCE40-LP384-CM3636-ball ucBGA (2.5 x 2.5 mm)0.40 mm25--lp384 --package cm36-d 384 -P cm36-d lp384
iCE40-LP1K-CM3636-ball ucBGA (2.5 x 2.5 mm)0.40 mm25--lp1k --package cm36-d 1k -P cm36-d lp1k
iCE40-LP384-CM4949-ball ucBGA (3 x 3 mm)0.40 mm37--lp384 --package cm49-d 384 -P cm49-d lp384
iCE40-LP1K-CM4949-ball ucBGA (3 x 3 mm)0.40 mm35--lp1k --package cm49-d 1k -P cm49-d lp1k
iCE40-LP1K-CM8181-ball ucBGA (4 x 4 mm)0.40 mm63--lp1k --package cm81-d 1k -P cm81-d lp1k
iCE40-LP4K-CM8181-ball ucBGA (4 x 4 mm)0.40 mm63--lp8k --package cm81:4k-d 8k -P cm81:4k-d lp8k
iCE40-LP8K-CM8181-ball ucBGA (4 x 4 mm)0.40 mm63--lp9k --package cm81-d 8k -P cm81-d lp8k
iCE40-LP1K-CM121121-ball ucBGA (5 x 5 mm)0.40 mm95--lp1k --package cm121-d 1k -P cm121-d lp1k
iCE40-LP4K-CM121121-ball ucBGA (5 x 5 mm)0.40 mm93--lp8k --package cm121:4k-d 8k -P cm121:4k-d lp8k
iCE40-LP8K-CM121121-ball ucBGA (5 x 5 mm)0.40 mm93--lp8k --package cm121-d 8k -P cm121-d lp8k
iCE40-LP4K-CM225225-ball ucBGA (7 x 7 mm)0.40 mm167--lp8k --package cm225:4k-d 8k -P cm225:4k-d lp8k
iCE40-LP8K-CM225225-ball ucBGA (7 x 7 mm)0.40 mm178--lp8k --package cm225-d 8k -P cm225-d lp8k
iCE40-HX8K-CM225225-ball ucBGA (7 x 7 mm)0.40 mm178--hx8k --package cm225-d 8k -P cm225-d hx8k
iCE40-LP384-QN3232-pin QFN (5 x 5 mm)0.50 mm21--lp384 --package qn32-d 384 -P qn32-d lp384
iCE40-UP5K-SG4848-pin QFN (7 x 7 mm)0.50 mm39--up5k --package sg48-d 5k -P sg48-d up5k
iCE40-LP1K-QN8484-pin QFNS (7 x 7 mm)0.50 mm67--lp1k --package qn84-d 1k -P qn84-d lp1k
iCE40-LP1K-CB8181-ball csBGA (5 x 5 mm)0.50 mm62--lp1k --package cb81-d 1k -P cb81-d lp1k
iCE40-LP1K-CB121121-ball csBGA (6 x 6 mm)0.50 mm92--lp1k --package cb121-d 1k -P cb121-d lp1k
iCE40-HX1K-CB132132-ball csBGA (8 x 8 mm)0.50 mm95--hx1k --package cb132-d 1k -P cb132-d hx1k
iCE40-HX4K-CB132132-ball csBGA (8 x 8 mm)0.50 mm95--hx8k --package cb132:4k-d 8k -P cb132:4k-d hx8k
iCE40-HX8K-CB132132-ball csBGA (8 x 8 mm)0.50 mm95--hx8k --package cb132-d 8k -P cb132-d hx8k
iCE40-HX1K-VQ100100-pin VQFP (14 x 14 mm)0.50 mm72--hx1k --package vq100-d 1k -P vq100-d hx1k
iCE40-HX1K-TQ144144-pin TQFP (20 x 20 mm)0.50 mm96--hx1k --package tq144-d 1k -P tq144-d hx1k
iCE40-HX4K-TQ144144-pin TQFP (20 x 20 mm)0.50 mm107--hx8k --package tq144:4k-d 8k -P tq144:4k-d hx8k
iCE40-HX4K-BG121121-ball caBGA (9 x 9 mm)0.80 mm93--hx8k --package bg121:4k-d 8k -P bg121:4k-d hx8k
iCE40-HX8K-BG121121-ball caBGA (9 x 9 mm)0.80 mm93--hx8k --package bg121-d 8k -P bg121-d hx8k
iCE40-HX8K-CT256256-ball caBGA (14 x 14 mm)0.80 mm206--hx8k --package ct256-d 8k -P ct256-d hx8k
- -

-Current work focuses on further improving our timing analysis flow. -

- -

How do I use the Fully Open Source iCE40 Flow?

- -

-Synthesis for iCE40 FPGAs can be done with Yosys. -Place-and-route can be done with arachne-pnr. -Here is an example script for implementing and programming the rot example from -arachne-pnr (this example targets the iCEstick development board): -

- -
yosys -p "synth_ice40 -blif rot.blif" rot.v
-arachne-pnr -d 1k -p rot.pcf rot.blif -o rot.asc
-icepack rot.asc rot.bin
-iceprog rot.bin
- -

-A simple timing analysis report can be generated using the icetime utility: -

- -
icetime -tmd hx1k rot.asc
- -

Where are the Tools? How to install?

- -

-Installing prerequisites (this command is for Ubuntu 14.04): -

- -
-sudo apt-get install build-essential clang bison flex libreadline-dev \
-                     gawk tcl-dev libffi-dev git mercurial graphviz   \
-                     xdot pkg-config python python3 libftdi-dev \
-                     qt5-default python3-dev libboost-all-dev cmake libeigen3-dev
-
- -

-On Fedora 24 the following command installs all prerequisites: -

- -
-sudo dnf install make automake gcc gcc-c++ kernel-devel clang bison \
-                 flex readline-devel gawk tcl-devel libffi-devel git mercurial \
-                 graphviz python-xdot pkgconfig python python3 libftdi-devel \
-                 qt5-devel python3-devel boost-devel boost-python3-devel eigen3-devel
-
- -

-Note: All tools will be installed relative to /usr/local -

- -

-Installing the IceStorm Tools (icepack, icebox, iceprog, icetime, chip databases): -

- -
git clone https://github.com/YosysHQ/icestorm.git icestorm
-cd icestorm
-make -j$(nproc)
-sudo make install
- -

-Installing Arachne-PNR (place&route tool, predecessor to NextPNR): -

- -
git clone https://github.com/cseed/arachne-pnr.git arachne-pnr
-cd arachne-pnr
-make -j$(nproc)
-sudo make install
- -

-Installing NextPNR (place&route tool, Arachne-PNR replacement): -

- -
git clone --recursive https://github.com/YosysHQ/nextpnr nextpnr
-cd nextpnr
-cmake -DARCH=ice40 -DCMAKE_INSTALL_PREFIX=/usr/local .
-make -j$(nproc)
-sudo make install
- -

-Installing Yosys (Verilog synthesis): -

- -
git clone https://github.com/YosysHQ/yosys.git yosys
-cd yosys
-make -j$(nproc)
-sudo make install
- -

-Both place and route tools (Arachne-PNR & NextPNR) convert the IceStorm -text chip databases into the respective PNR binary chip databases during build. -Always rebuild the PNR tools after updating your IceStorm installation. -

- -

-Notes for Linux: Create a file /etc/udev/rules.d/53-lattice-ftdi.rules with the following line in it to allow uploading -bit-streams to a Lattice iCEstick and/or a Lattice iCE40-HX8K Breakout Board as unprivileged user: -

- -
ATTRS{idVendor}=="0403", ATTRS{idProduct}=="6010", MODE="0660", GROUP="plugdev", TAG+="uaccess"
- -

-Notes for Archlinux: just install icestorm-git, arachne-pnr-git and yosys-git from the Arch User Repository (no need to follow the install instructions above). -

- -

-Notes for OSX: Please follow the additional instructions for OSX to install on OSX. -

- -

-Please file an issue on github if you have additional notes to -share regarding the install procedures on the operating system of your choice. -

- -

What are the IceStorm Tools?

- -

-The IceStorm Tools are a couple of small programs for working with iCE40 bitstream files and our -ASCII representation of it. The complete Open Source iCE40 Flow consists of the IceStorm Tools, Arachne-PNR, and Yosys. -

- -

IcePack/IceUnpack

- -

-The iceunpack program converts an iCE40 .bin file into the IceStorm ASCII format -that has blocks of 0 and 1 for the config bits for each tile in the chip. The -icepack program converts such an ASCII file back to an iCE40 .bin file. All -other IceStorm Tools operate on the ASCII file format, not the bitstream binaries. -

- -

IceTime

- -

-The icetime program is an iCE40 timing analysis tool. It reads designs in IceStorm ASCII format and writes times timing -netlists that can be used in external timing analysers. It also includes a simple topological timing analyser that can be used to create timing reports. -

- -

IceBox

- -

-A python library and various tools for working with IceStorm ASCII files and accessing -the device database. For example icebox_vlog converts our ASCII file -dump of a bitstream into a Verilog file that implements an equivalent circuit. -

- -

IceProg

- -

-A small driver program for the FTDI-based programmer used on the iCEstick and HX8K development boards. -

- -

IceMulti

- -

-A tool for packing multiple bitstream files into one iCE40 multiboot image file. -

- -

IcePLL

- -

-A small program for calculating iCE40 PLL configuration parameters. -

- -

IceBRAM

- -

-A small program for swapping the BRAM contents in IceStorm ASCII files. E.g. -for changing the firmware image in a SoC design without re-running synthesis -and place&route. -

- -

ChipDB

- -

-The IceStorm Makefile builds and installs two files: chipdb-1k.txt and chipdb-8k.txt. -This files contain all the relevant information for arachne-pnr to place&route a design and -create an IceStorm ASCII file for the placed and routed design. -

- -

-IcePack/IceUnpack, IceBox, IceProg, IceTime, and IcePLL are written by Claire Wolf. IcePack/IceUnpack is based on a reference implementation provided by Mathias Lasser. IceMulti is written by Marcus Comstedt. -

- -

Where do I get support or meet other IceStorm users?

- -

-If you have a question regarding the IceStorm flow, use the yosys tag on stackoverflow -to ask your question. If your question is a general question about Verilog HDL design, please consider using the -verilog tag on stackoverflow instead. -

- -

-For general discussions go to the Yosys Subreddit or #yosys on freenode IRC. -

- -

-If you have a bug report please file an issue on github. (IceStorm Issue Tracker, -Yosys Issue Tracker, Arachne-PNR Issue Tracker) -

- -

Where is the Documentation?

- -

-Recommended reading: -Lattice iCE40 LP/HX Family Datasheet, -Lattice iCE Technology Library -(Especially the three pages on "Architecture Overview", "PLB Blocks", "Routing", and "Clock/Control Distribution Network" in -the Lattice iCE40 LP/HX Family Datasheet. Read that first, then come back here.) -

- -

-The FPGA fabric is divided into tiles. There are IO, RAM and LOGIC tiles. -

- - - -

-The iceunpack program can be used to convert the bitstream into an ASCII file -that has a block of 0 and 1 characters for each tile. For example: -

- -
.logic_tile 12 12
-000000000000000000000000000000000000000000000000000000
-000000000000000000000011010000000000000000000000000000
-000000000000000000000000000000000000000000000000000000
-000000000000000000000000000000000000000000000000000000
-000000000000000000000000000000000000000000000000000000
-000000000000000000000000000000000000000000000000000000
-000000000000000000000000000000000000000000000000000000
-000000000000001011000000000000000000000000000000000000
-000000000000000000000000000000000000000000000000000000
-000000000000000000000000000000000000000000000000000000
-000000000000000000000000000000000000000000000000000000
-000000000000000000000000000000000000000000000000000000
-000000000000000000000000000000000000000000000000000000
-000000000000000000000000000000000000000000000000000000
-000000000000000000000000001000001000010101010000000000
-000000000000000000000000000101010000101010100000000000
- -

-This bits are referred to as By[x] in the documentation. For example, B0 is the first -line, B0[0] the first bit in the first line, and B15[53] the last bit in the last line. -

- -

-The icebox_explain program can be used to turn this block of config bits into a description of the cell -configuration: -

- -
.logic_tile 12 12
-LC_7 0101010110101010 0000
-buffer local_g0_2 lutff_7/in_3
-buffer local_g1_4 lutff_7/in_0
-buffer sp12_h_r_18 local_g0_2
-buffer sp12_h_r_20 local_g1_4
- -

-IceBox contains a database of the wires and configuration bits that can be found in iCE40 tiles. This database can be accessed -via the IceBox Python API. But IceBox is a large hack. So it is recommended to only use the IceBox API -to export this database into a format that fits the target application. See icebox_chipdb for -an example program that does that. -

- -

-The recommended approach for learning how to use this documentation is to -synthesize very simple circuits using Yosys and Arachne-pnr, run the icestorm -tool icebox_explain on the resulting bitstream files, and analyze the -results using the HTML export of the database mentioned above. -icebox_vlog can be used to convert the bitstream to Verilog. The -output file of this tool will also outline the signal paths in comments added -to the generated Verilog code. -

- -

-For example, consider the following Verilog and PCF files: -

- -
// example.v
-module top (input a, b, output y);
-  assign y = a & b;
-endmodule
-
-# example.pcf
-set_io a 1
-set_io b 10
-set_io y 11
- -

-And run them through Yosys, Arachne-PNR and IcePack: -

- -
$ yosys -p 'synth_ice40 -top top -blif example.blif' example.v
-$ arachne-pnr -d 1k -o example.asc -p example.pcf example.blif
-$ icepack example.asc example.bin
-
- -

-We would get something like the following icebox_explain output: -

- -
$ icebox_explain example.asc
-Reading file 'example.asc'..
-Fabric size (without IO tiles): 12 x 16
-
-.io_tile 0 10
-IOB_1 PINTYPE_0
-IOB_1 PINTYPE_3
-IOB_1 PINTYPE_4
-IoCtrl IE_0
-IoCtrl IE_1
-IoCtrl REN_0
-buffer local_g0_5 io_1/D_OUT_0
-buffer logic_op_tnr_5 local_g0_5
-
-.io_tile 0 14
-IOB_1 PINTYPE_0
-IoCtrl IE_1
-IoCtrl REN_0
-buffer io_1/D_IN_0 span4_vert_b_6
-
-.io_tile 0 11
-IOB_0 PINTYPE_0
-IoCtrl IE_0
-IoCtrl REN_1
-routing span4_vert_t_14 span4_horz_13
-
-.logic_tile 1 11
-LC_5 0001000000000000 0000
-buffer local_g0_0 lutff_5/in_1
-buffer local_g3_0 lutff_5/in_0
-buffer neigh_op_lft_0 local_g0_0
-buffer sp4_h_r_24 local_g3_0
- -

-And something like the following icebox_vlog output: -

- -
$ icebox_vlog -p example.pcf example.asc
-// Reading file 'example.asc'..
-
-module chip (output y, input b, input a);
-
-wire y;
-// io_0_10_1
-// (0, 10, 'io_1/D_OUT_0')
-// (0, 10, 'io_1/PAD')
-// (0, 10, 'local_g0_5')
-// (0, 10, 'logic_op_tnr_5')
-// (0, 11, 'logic_op_rgt_5')
-// (0, 12, 'logic_op_bnr_5')
-// (1, 10, 'neigh_op_top_5')
-// (1, 11, 'lutff_5/out')
-// (1, 12, 'neigh_op_bot_5')
-// (2, 10, 'neigh_op_tnl_5')
-// (2, 11, 'neigh_op_lft_5')
-// (2, 12, 'neigh_op_bnl_5')
-
-wire b;
-// io_0_11_0
-// (0, 11, 'io_0/D_IN_0')
-// (0, 11, 'io_0/PAD')
-// (1, 10, 'neigh_op_tnl_0')
-// (1, 10, 'neigh_op_tnl_4')
-// (1, 11, 'local_g0_0')
-// (1, 11, 'lutff_5/in_1')
-// (1, 11, 'neigh_op_lft_0')
-// (1, 11, 'neigh_op_lft_4')
-// (1, 12, 'neigh_op_bnl_0')
-// (1, 12, 'neigh_op_bnl_4')
-
-wire a;
-// io_0_14_1
-// (0, 11, 'span4_horz_13')
-// (0, 11, 'span4_vert_t_14')
-// (0, 12, 'span4_vert_b_14')
-// (0, 13, 'span4_vert_b_10')
-// (0, 14, 'io_1/D_IN_0')
-// (0, 14, 'io_1/PAD')
-// (0, 14, 'span4_vert_b_6')
-// (0, 15, 'span4_vert_b_2')
-// (1, 11, 'local_g3_0')
-// (1, 11, 'lutff_5/in_0')
-// (1, 11, 'sp4_h_r_24')
-// (1, 13, 'neigh_op_tnl_2')
-// (1, 13, 'neigh_op_tnl_6')
-// (1, 14, 'neigh_op_lft_2')
-// (1, 14, 'neigh_op_lft_6')
-// (1, 15, 'neigh_op_bnl_2')
-// (1, 15, 'neigh_op_bnl_6')
-// (2, 11, 'sp4_h_r_37')
-// (3, 11, 'sp4_h_l_37')
-
-assign y = /* LUT    1 11  5 */ b ? a : 0;
-
-endmodule
- -

Links

- -

-Links to related projects. Contact me at claire@clairexen.net if you have an interesting and relevant link. -

- - - -

iCE40 Boards

- - - -

Lectures and Tutorials

- - - -

Other FPGA bitstream documentation projects

- - - -
- -

-In papers and reports, please refer to Project IceStorm as follows: Claire Wolf, Mathias Lasser. Project IceStorm. http://bygone.clairexen.net/icestorm/, -e.g. using the following BibTeX code: -

- -
@MISC{IceStorm,
-	author = {Claire Wolf and Mathias Lasser},
-	title = {Project IceStorm},
-	howpublished = "\url{http://bygone.clairexen.net/icestorm/}"
-}
- -
- -

-Documentation mostly by Claire Wolf <claire@clairexen.net> in 2015. Based on research by Mathias Lasser and Claire Wolf.
-Buy an iCEstick or iCE40-HX8K Breakout Board from Lattice and see what you can do with the tools and information provided here. -

- - diff --git a/docs/io_tile.html b/docs/io_tile.html deleted file mode 100644 index 2b074ca..0000000 --- a/docs/io_tile.html +++ /dev/null @@ -1,516 +0,0 @@ - - - -Project IceStorm – IO Tile Documentation - -

Project IceStorm – IO Tile Documentation

- -

-Project IceStorm aims at documenting the bitstream format of Lattice iCE40 -FPGAs and providing simple tools for analyzing and creating bitstream files. -This is work in progress. -

- -

Span-4 and Span-12 Wires

- -

IO Tile Span-Wires

- -

-The image on the right shows the span-wires of a left (or right) io cell (click to enlarge). -

- -

-A left/right io cell has 16 connections named span4_vert_t_0 to span4_vert_t_15 on its top edge and -16 connections named span4_vert_b_0 to span4_vert_b_15 on its bottom edge. The nets span4_vert_t_0 -to span4_vert_t_11 are connected to span4_vert_b_4 to span4_vert_b_15. The span-4 and span-12 wires -of the adjacent logic cell are connected to the nets span4_horz_0 to span4_horz_47 and span12_horz_0 -to span12_horz_23. -

- -

-A top/bottom io cell has 16 connections named span4_horz_l_0 to span4_horz_l_15 on its left edge and -16 connections named span4_horz_r_0 to span4_horz_r_15 on its right edge. The nets span4_horz_l_0 -to span4_horz_l_11 are connected to span4_horz_r_4 to span4_horz_r_15. The span-4 and span-12 wires -of the adjacent logic cell are connected to the nets span4_vert_0 to span4_vert_47 and span12_vert_0 -to span12_vert_23. -

- -

-The vertical span4 wires of left/right io cells are connected "around the corner" to the horizontal span4 wires of the top/bottom -io cells. For example span4_vert_b_0 of IO cell (0 1) is connected to span4_horz_l_0 (span4_horz_r_4) -of IO cell (1 0). -

- -

-Note that unlike the span-wires connection LOGIC and RAM tiles, the span-wires -connecting IO tiles to each other are not pairwise crossed out. -

- -

IO Blocks

- -

-Each IO tile contains two IO blocks. Each IO block essentially implements the SB_IO -primitive from the Lattice iCE Technology Library. -Some inputs are shared between the two IO blocks. The following table lists how the -wires in the logic tile map to the SB_IO primitive ports: -

- - - - - - - - - - - - -
SB_IO PortIO Block 0IO Block 1
D_IN_0io_0/D_IN_0io_1/D_IN_0
D_IN_1io_0/D_IN_1io_1/D_IN_1
D_OUT_0io_0/D_OUT_0io_1/D_OUT_0
D_OUT_1io_0/D_OUT_1io_1/D_OUT_1
OUTPUT_ENABLEio_0/OUT_ENBio_1/OUT_ENB
CLOCK_ENABLEio_global/cen
INPUT_CLKio_global/inclk
OUTPUT_CLKio_global/outclk
LATCH_INPUT_VALUEio_global/latch
- -

-Like the inputs to logic cells, the inputs to IO blocks are routed to the IO block via a two-stage process. A signal -is first routed to one of 16 local tracks in the IO tile and then from the local track to the IO block. -

- -

-The io_global/latch signal is shared among all IO tiles on an edge of the chip and is driven by fabout -from one dedicated IO tile on that edge. For the HX1K chips the tiles driving the io_global/latch signal are: -(0, 7), (13, 10), (5, 0), and (8, 17) -

- -

-A logic tile sends the output of its eight logic cells to its neighbour tiles. An IO tile does the same thing with the four D_IN -signals created by its two IO blocks. The D_IN signals map to logic function indices as follows: -

- - - - - - - - - - - -
Function IndexD_IN Wire
0io_0/D_IN_0
1io_0/D_IN_1
2io_1/D_IN_0
3io_1/D_IN_1
4io_0/D_IN_0
5io_0/D_IN_1
6io_1/D_IN_0
7io_1/D_IN_1
- -

-For example the signal io_1/D_IN_0 in IO tile (0, 5) can be seen as neigh_op_lft_2 and neigh_op_lft_6 in LOGIC tile (1, 5). -

- -

-Each IO Tile has 2 NegClk configuration bits, suggesting that the -clock signals can be inverted independently for the the two IO blocks in the -tile. However, the Lattice tools refuse to pack two IO blocks with different clock -polarity into the same IO tile. In our tests we only managed to either set or clear -both NegClk bits. -

- -

-Each IO block has two IoCtrl IE bits that enable the input buffers and -two IoCtrl REN bits that enable the pull up resistors. Both bits are active -low, i.e. an unused IO tile will have both IE bits set and both REN bits cleared (the -default behavior is to enable pullup resistors on all unused pins). Note that -icebox_explain.py will ignore all IO tiles that only have the two IoCtrl -IE bits set. -

- -

-However, the IoCtrl IE_0/IE_1 and IoCtrl REN_0/REN_1 do not -necessarily configure the IO PIN that are connected to the IO block in the same tile, -and if they do the numbers (0/1) do not necessarily match. As a general rule, the pins -on the right and bottom side of the chips match up with the IO blocks and for the pins -on the left and top side the numbers must be swapped. But in some cases the IO block -and the set of IE/REN are not even located in the same tile. The following -table lists the correlation between IO blocks and IE/REN bits for the -1K chip: -

- - -
- - - - - - - - - - - - - - - - - - - - - - - - - - - -
IO BlockIE/REN Block
0 14 10 14 0
0 14 00 14 1
0 13 10 13 0
0 13 00 13 1
0 12 10 12 0
0 12 00 12 1
0 11 10 11 0
0 11 00 11 1
0 10 10 10 0
0 10 00 10 1
0 9 10 9 0
0 9 00 9 1
0 8 10 8 0
0 8 00 8 1
0 6 10 6 0
0 6 00 6 1
0 5 10 5 0
0 5 00 5 1
0 4 10 4 0
0 4 00 4 1
0 3 10 3 0
0 3 00 3 1
0 2 10 2 0
0 2 00 2 1
- -		 - - - - - - - - - - - - - - - - - - - - - - - - - - - -
IO BlockIE/REN Block
1 0 0 1 0 0
1 0 1 1 0 1
2 0 0 2 0 0
2 0 1 2 0 1
3 0 0 3 0 0
3 0 1 3 0 1
4 0 0 4 0 0
4 0 1 4 0 1
5 0 0 5 0 0
5 0 1 5 0 1
6 0 1 6 0 0
7 0 0 6 0 1
6 0 0 7 0 0
7 0 1 7 0 1
8 0 0 8 0 0
8 0 1 8 0 1
9 0 0 9 0 0
9 0 1 9 0 1
10 0 010 0 0
10 0 110 0 1
11 0 011 0 0
11 0 111 0 1
12 0 012 0 0
12 0 112 0 1
- -		 - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
IO BlockIE/REN Block
13 1 013 1 0
13 1 113 1 1
13 2 013 2 0
13 2 113 2 1
13 3 113 3 1
13 4 013 4 0
13 4 113 4 1
13 6 013 6 0
13 6 113 6 1
13 7 013 7 0
13 7 113 7 1
13 8 013 8 0
13 8 113 8 1
13 9 013 9 0
13 9 113 9 1
13 11 013 10 0
13 11 113 10 1
13 12 013 11 0
13 12 113 11 1
13 13 013 13 0
13 13 113 13 1
13 14 013 14 0
13 14 113 14 1
13 15 013 15 0
13 15 113 15 1
- -		 - - - - - - - - - - - - - - - - - - - - - - - - - - -
IO BlockIE/REN Block
12 17 112 17 1
12 17 012 17 0
11 17 111 17 1
11 17 011 17 0
10 17 1 9 17 1
10 17 0 9 17 0
9 17 110 17 1
9 17 010 17 0
8 17 1 8 17 1
8 17 0 8 17 0
7 17 1 7 17 1
7 17 0 7 17 0
6 17 1 6 17 1
5 17 1 5 17 1
5 17 0 5 17 0
4 17 1 4 17 1
4 17 0 4 17 0
3 17 1 3 17 1
3 17 0 3 17 0
2 17 1 2 17 1
2 17 0 2 17 0
1 17 1 1 17 1
1 17 0 1 17 0
- -
- -

-When an input pin pair is used as LVDS pair (IO standard -SB_LVDS_INPUT, bank 3 / left edge only), then the four bits -IoCtrl IE_0/IE_1 and IoCtrl REN_0/REN_1 are all set, as well -as the IoCtrl LVDS bit. -

- -

-In the iCE 8k devices the IoCtrl IE bits are active high. So an unused -IO tile on an 8k chip has all bits cleared. -

- -

Global Nets

- -

-iCE40 FPGAs have 8 global nets. Each global net can be driven directly from an -IO pin. In the FPGA bitstream, routing of external signals to global nets is -not controlled by bits in the IO tile. Instead bits that do not belong to any -tile are used. In IceBox nomenclature such bits are called "extra bits". -

- -

-The following table lists which pins / IO blocks may be used to drive -which global net, and what .extra statements in the IceStorm ASCII file -format to represent the corresponding configuration bits: -

- - - - - - - - - - - - -
Glb NetPin
(HX1K-TQ144)		IO Tile +
Block #		IceBox Statement
0 9313 8 1.extra_bit 0 330 142
1 21 0 8 1.extra_bit 0 331 142
2128 7 17 0.extra_bit 1 330 143
3 50 7 0 0.extra_bit 1 331 143
4 20 0 9 0.extra_bit 1 330 142
5 9413 9 0.extra_bit 1 331 142
6 49 6 0 1.extra_bit 0 330 143
7129 6 17 1.extra_bit 0 331 143
- -

-Signals internal to the FPGA can also be routed to the global nets. This is done by routing the signal -to the fabout net on an IO tile. The same set of I/O tiles is used for this, but in this -case each of the I/O tiles corresponds to a different global net: -

- - - - - - - - - - - - - - - - - - - - -
Glb Net01234567
IO Tile 7 0 7 1713 9 0 9 6 17 6 0 0 813 8
- -

Column Buffers

- -

Column Buffer Control Bits

- -

-Each LOGIC, IO, and RAMB tile has 8 ColBufCtrl bits, one for each global net. In most tiles this -bits have no function, but in tiles in rows 4, 5, 12, and 13 (for RAM columns: rows 3, 5, 11, and 13) this bits -control which global nets are driven to the column of tiles below and/or above that tile (including that tile), -as illustrated in the image to the right (click to enlarge). -

- -

-In 8k chips the rows 8, 9, 24, and 25 contain the column buffers. 8k RAMB and -RAMT tiles can control column buffers, so the pattern looks the same for RAM, LOGIC, and -IO columns. -

- -

Warmboot

- -

-The SB_WARMBOOT primitive in iCE40 FPGAs has three inputs and no outputs. The three inputs of that cell -are driven by the fabout signal from three IO tiles. In HX1K chips the tiles connected to the -SB_WARMBOOT primitive are: -

- - - - - - -
Warmboot PinIO Tile
BOOT12 0
S013 1
S113 2
- -

PLL Cores

- -

-The PLL primitives in iCE40 FPGAs are configured using the PLLCONFIG_* -bits in the IO tiles. The configuration for a single PLL cell is spread out -over many IO tiles. For example, the PLL cell in the 1K chip are configured as -follows (bits listed from LSB to MSB): -

- - -
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
IO TileConfig BitSB_PLL40_* Parameter
0 3PLLCONFIG_5Select PLL Type:
-000 = DISABLED
-010 = SB_PLL40_PAD
-100 = SB_PLL40_2_PAD
-110 = SB_PLL40_2F_PAD
-011 = SB_PLL40_CORE
-111 = SB_PLL40_2F_CORE
0 5PLLCONFIG_1
0 5PLLCONFIG_3
0 5PLLCONFIG_5FEEDBACK_PATH
-000 = "DELAY"
-001 = "SIMPLE"
-010 = "PHASE_AND_DELAY"
-110 = "EXTERNAL"
0 2PLLCONFIG_9
0 3PLLCONFIG_1
0 4PLLCONFIG_4DELAY_ADJUSTMENT_MODE_FEEDBACK
-0 = "FIXED"
-1 = "DYNAMIC"
0 4PLLCONFIG_9DELAY_ADJUSTMENT_MODE_RELATIVE
-0 = "FIXED"
-1 = "DYNAMIC"
0 3PLLCONFIG_6PLLOUT_SELECT
PLLOUT_SELECT_PORTA
-00 = "GENCLK"
-01 = "GENCLK_HALF"
-10 = "SHIFTREG_90deg"
-11 = "SHIFTREG_0deg"
0 3PLLCONFIG_7
0 3PLLCONFIG_2PLLOUT_SELECT_PORTB
-00 = "GENCLK"
-01 = "GENCLK_HALF"
-10 = "SHIFTREG_90deg"
-11 = "SHIFTREG_0deg"
0 3PLLCONFIG_3
0 3PLLCONFIG_4SHIFTREG_DIV_MODE
0 3PLLCONFIG_8TEST_MODE
0 5PLLCONFIG_2Enable ICEGATE for PLLOUTGLOBALA
0 5PLLCONFIG_4Enable ICEGATE for PLLOUTGLOBALB
 - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
IO TileConfig BitSB_PLL40_* Parameter
0 3PLLCONFIG_9FDA_FEEDBACK
0 4PLLCONFIG_1
0 4PLLCONFIG_2
0 4PLLCONFIG_3
0 5PLLCONFIG_5FDA_RELATIVE
0 4PLLCONFIG_6
0 4PLLCONFIG_7
0 4PLLCONFIG_8
0 1PLLCONFIG_1DIVR
0 1PLLCONFIG_2
0 1PLLCONFIG_3
0 1PLLCONFIG_4
0 1PLLCONFIG_5DIVF
0 1PLLCONFIG_6
0 1PLLCONFIG_7
0 1PLLCONFIG_8
0 1PLLCONFIG_9
0 2PLLCONFIG_1
0 2PLLCONFIG_2
0 2PLLCONFIG_3DIVQ
0 2PLLCONFIG_4
0 2PLLCONFIG_5
0 2PLLCONFIG_6FILTER_RANGE
0 2PLLCONFIG_7
0 2PLLCONFIG_8
-
- -

-The PLL inputs are routed to the PLL via the fabout signal from various IO tiles. The non-clock -PLL outputs are routed via otherwise unused neigh_op_* signals in fabric corners. For example in case -of the 1k chip: -

- - - - - - - - - - - - - - - - - - - - -
TileNet-SegmentSB_PLL40_* Port Name
0 1faboutREFERENCECLK
0 2faboutEXTFEEDBACK
0 4faboutDYNAMICDELAY
0 5fabout
0 6fabout
0 10fabout
0 11fabout
0 12fabout
0 13fabout
0 14fabout
1 1neigh_op_bnl_1LOCK
1 0faboutBYPASS
2 0faboutRESETB
5 0faboutLATCHINPUTVALUE
12 1neigh_op_bnr_3SDO
4 0faboutSDI
3 0faboutSCLK
- -

-The PLL clock outputs are fed directly into the input path of certain IO tiles. -In case of the 1k chip the PORTA clock is fed into PIO 1 of IO Tile (6 0) and -the PORTB clock is fed into PIO 0 of IO Tile (7 0). Because of this, those two -PIOs can only be used as output Pins by the FPGA fabric when the PLL ports -are being used. -

- -

-The input path that are stolen are also used to implement the ICEGATE function. -If the input pin type of the input path being stolen is set to -PIN_INPUT_LATCH, then the ICEGATE -function is enabled for the corresponding CORE -output of the PLL. -

- - diff --git a/docs/logic_tile.html b/docs/logic_tile.html deleted file mode 100644 index 94df5a9..0000000 --- a/docs/logic_tile.html +++ /dev/null @@ -1,318 +0,0 @@ - - - -Project IceStorm – LOGIC Tile Documentation - -

Project IceStorm – LOGIC Tile Documentation

- -

-Project IceStorm aims at documenting the bitstream format of Lattice iCE40 -FPGAs and providing simple tools for analyzing and creating bitstream files. -This is work in progress. -

- -

Span-4 and Span-12 Wires

- -

-The span-4 and span-12 wires are the main interconnect resource in iCE40 FPGAs. They "span" (have a length of) -4 or 12 cells in horizontal or vertical direction. -

- -

-All routing resources in iCE40 are directional tristate buffers. The bits marked routing -use the all-zeros config pattern for tristate, while the bits marked buffer have -a dedicated buffer-enable bit, which is 1 in all non-tristate configurations. -

- -

Span-4 Horizontal

- -

Span-4 Horizontal

- -

-The image on the right shows the horizontal span-4 wires of a logic or ram cell (click to enlarge). -

- -

-On the left side of the cell there are 48 connections named sp4_h_l_0 to sp4_h_l_47. The lower 36 of those -wires are connected to sp4_h_r_12 to sp4_h_r_47 on the right side of the cell. (IceStorm normalizes this -wire names to sp4_h_r_0 to sp4_h_r_35. Note: the Lattice tools use a different normalization scheme -for this wire names.) The wires connecting the left and right horizontal span-4 ports are pairwise crossed-out. -

- -

-The wires sp4_h_l_36 to sp4_h_l_47 terminate in the cell as do the wires sp4_h_r_0 to sp4_h_r_11. -

- -

-This wires "span" 4 cells, i.e. they connect 5 cells if you count the cells on -both ends of the wire. -

- -

-For example, the wire sp4_h_r_0 in cell (x, y) has the following names: -

- - - - - - - - -
Cell Coordinatessp4_h_l_* wire namesp4_h_r_* wire name
x, y-sp4_h_r_0
x+1, ysp4_h_l_0sp4_h_r_13
x+2, ysp4_h_l_13sp4_h_r_24
x+3, ysp4_h_l_24sp4_h_r_37
x+4, ysp4_h_l_37-
- -

Span-4 Vertical

- -

Span-4 Vertical

- -

-The image on the right shows the vertical span-4 wires of a logic or ram cell (click to enlarge). -

- -

-Similar to the horizontal span-4 wires there are 48 connections on the top (sp4_v_t_0 to sp4_v_t_47) and -48 connections on the bottom (sp4_v_b_0 to sp4_v_b_47). The wires sp4_v_t_0 to sp4_v_t_35 -are connected to sp4_v_b_12 to sp4_v_b_47 (with pairwise crossing out). Wire names are normalized -to sp4_v_b_12 to sp4_v_b_47. -

- -

-But in addition to that, each cell also has access to sp4_v_b_0 to sp4_v_b_47 of its right neighbour. -This are the wires sp4_r_v_b_0 to sp4_r_v_b_47. So over all a single vertical span-4 wire -connects 9 cells. For example, the wire sp4_v_b_0 in cell (x, y) has the following names: -

- - - - - - - - - - - - -
Cell Coordinatessp4_v_t_* wire namesp4_v_b_* wire namesp4_r_v_b_* wire name
x, y-sp4_v_b_0-
x, y-1sp4_v_t_0sp4_v_b_13-
x, y-2sp4_v_t_13sp4_v_b_24-
x, y-3sp4_v_t_24sp4_v_b_37-
x, y-4sp4_v_t_37--
x-1, y--sp4_r_v_b_0
x-1, y-1--sp4_r_v_b_13
x-1, y-2--sp4_r_v_b_24
x-1, y-3--sp4_r_v_b_37
- -

Span-12 Horizontal and Vertical

- -

-Similar to the span-4 wires there are also longer horizontal and vertical span-12 wires. -

- -

-There are 24 connections sp12_v_t_0 to sp12_v_t_23 on the top of the -cell and 24 connections sp12_v_b_0 to sp12_v_b_23 on the bottom of the -cell. The wires sp12_v_t_0 to sp12_v_t_21 are connected to -sp12_v_b_2 to sp12_v_b_23 (with pairwise crossing out). The connections -sp12_v_b_0, sp12_v_b_1, sp12_v_t_22, and sp12_v_t_23 -terminate in the cell. Wire names are normalized to sp12_v_b_2 to sp12_v_b_23. -

- -

-There are also 24 connections sp12_h_l_0 to sp12_h_l_23 on the left of the -cell and 24 connections sp12_h_r_0 to sp12_h_r_23 on the right of the -cell. The wires sp12_h_l_0 to sp12_h_l_21 are connected to -sp12_h_r_2 to sp12_h_r_23 (with pairwise crossing out). The connections -sp12_h_r_0, sp12_h_r_1, sp12_h_l_22, and sp12_h_l_23 -terminate in the cell. Wire names are normalized to sp12_v_r_2 to sp12_h_r_23. -

- -

Local Tracks

- -

-The local tracks are the gateway to the logic cell inputs. Signals from the span-wires -and the logic cell outputs of the eight neighbour cells can be routed to the local tracks and -signals from the local tracks can be routed to the logic cell inputs. -

- -

-Each logic tile has 32 local tracks. They are organized in 4 groups of 8 wires each: -local_g0_0 to local_g3_7. -

- -

-The span wires, global signals, and neighbour outputs can be routed to the local tracks. But not -all of those signals can be routed to all of the local tracks. Instead there is a different -mix of 16 signals for each local track. -

- -

-The buffer driving the local track has 5 configuration bits. One enable bit and 4 bits that select -the input wire. For example for local_g0_0 (copy&paste from the bitstream doku): -

- - - - - - - - - - - - - - - - - - - - -
B0[14]B1[14]B1[15]B1[16] B1[17]FunctionSource-NetDestination-Net
00001buffersp4_r_v_b_24local_g0_0
00011buffersp12_h_r_8local_g0_0
00101bufferneigh_op_bot_0local_g0_0
00111buffersp4_v_b_16local_g0_0
01001buffersp4_r_v_b_35local_g0_0
01011buffersp12_h_r_16local_g0_0
01101bufferneigh_op_top_0local_g0_0
01111buffersp4_h_r_0local_g0_0
10001bufferlutff_0/outlocal_g0_0
10011buffersp4_v_b_0local_g0_0
10101bufferneigh_op_lft_0local_g0_0
10111buffersp4_h_r_8local_g0_0
11001bufferneigh_op_bnr_0local_g0_0
11011buffersp4_v_b_8local_g0_0
11101buffersp12_h_r_0local_g0_0
11111buffersp4_h_r_16local_g0_0
- -

-Then the signals on the local tracks can be routed to the input pins of the logic cells. Like before, -not every local track can be routed to every logic cell input pin. Instead there is a different mix -of 16 local track for each logic cell input. For example for lutff_0/in_0: -

- - - - - - - - - - - - - - - - - - - - -
B0[26]B1[26]B1[27]B1[28]B1[29]FunctionSource-NetDestination-Net
00001bufferlocal_g0_0lutff_0/in_0
00011bufferlocal_g2_0lutff_0/in_0
00101bufferlocal_g1_1lutff_0/in_0
00111bufferlocal_g3_1lutff_0/in_0
01001bufferlocal_g0_2lutff_0/in_0
01011bufferlocal_g2_2lutff_0/in_0
01101bufferlocal_g1_3lutff_0/in_0
01111bufferlocal_g3_3lutff_0/in_0
10001bufferlocal_g0_4lutff_0/in_0
10011bufferlocal_g2_4lutff_0/in_0
10101bufferlocal_g1_5lutff_0/in_0
10111bufferlocal_g3_5lutff_0/in_0
11001bufferlocal_g0_6lutff_0/in_0
11011bufferlocal_g2_6lutff_0/in_0
11101bufferlocal_g1_7lutff_0/in_0
11111bufferlocal_g3_7lutff_0/in_0
- -

-The 8 global nets on the iCE40 can be routed to the local track via the glb2local_0 to glb2local_3 -nets using a similar two-stage process. The logic block clock-enable and set-reset inputs can be driven -directly from one of 4 global nets or from one of 4 local tracks. The logic block clock input can be driven -from any of the global nets and from a few local tracks. See the bitstream documentation for details. -

- -

Logic Block

- -

-Each logic tile has a logic block containing 8 logic cells. Each logic cell contains a 4-input LUT, a carry -unit and a flip-flop. Clock, clock enable, and set/reset inputs are shared along the 8 logic cells. So is the -bit that configures positive/negative edge for the flip flops. But the three configuration bits that specify if -the flip flop should be used, if it is set or reset by the set/reset input, and if the set/reset is synchronous -or asynchronous exist for each logic cell individually. -

- -

-Each LUT i has four input wires lutff_i/in_0 to lutff_i/in_3. Input -lutff_i/in_3 can be configured to be driven by the carry output of the previous logic cell, -or by carry_in_mux in case of i=0. Input lutff_i/in_2 can be configured to -be driven by the output of the previous LUT for i>0 (LUT cascade). The LUT uses its 4 input signals to -calculate lutff_i/lout. The signal is then passed through the built-in FF -and becomes lutff_i/out. With the exception of LUT cascades, only the signal -after the FF is visible from outside the logic block. -

- -

-The carry unit calculates lutff_i/cout = lutff_i/in_1 + lutff_i/in_2 + lutff_(i-1)/cout > 1. In case of i=0, carry_in_mux is used as third input. carry_in_mux can be configured to be constant 0, 1 or the lutff_7/cout signal from the logic tile below. -

- -

-Part of the functionality described above is documented as part of the routing -bitstream documentation (see the buffers for lutff_ inputs). The NegClk -bit switches all 8 FFs in the tile to negative edge mode. The CarryInSet -bit drives the carry_in_mux high (it defaults to low when not driven via the buffer from -carry_in). -

- -

-The remaining functions of the logic cell are configured via the LC_i bits. This -are 20 bit per logic cell. We have arbitrarily labeled those bits as follows: -

- - - - - - - - - - - - - - - - - - - - - - - -
LabelLC_0LC_1LC_2LC_3LC_4LC_5LC_6LC_7
LC_i[0]B0[36]B2[36]B4[36]B6[36]B8[36]B10[36]B12[36]B14[36]
LC_i[1]B0[37]B2[37]B4[37]B6[37]B8[37]B10[37]B12[37]B14[37]
LC_i[2]B0[38]B2[38]B4[38]B6[38]B8[38]B10[38]B12[38]B14[38]
LC_i[3]B0[39]B2[39]B4[39]B6[39]B8[39]B10[39]B12[39]B14[39]
LC_i[4]B0[40]B2[40]B4[40]B6[40]B8[40]B10[40]B12[40]B14[40]
LC_i[5]B0[41]B2[41]B4[41]B6[41]B8[41]B10[41]B12[41]B14[41]
LC_i[6]B0[42]B2[42]B4[42]B6[42]B8[42]B10[42]B12[42]B14[42]
LC_i[7]B0[43]B2[43]B4[43]B6[43]B8[43]B10[43]B12[43]B14[43]
LC_i[8]B0[44]B2[44]B4[44]B6[44]B8[44]B10[44]B12[44]B14[44]
LC_i[9]B0[45]B2[45]B4[45]B6[45]B8[45]B10[45]B12[45]B14[45]
LC_i[10]B1[36]B3[36]B5[36]B7[36]B9[36]B11[36]B13[36]B15[36]
LC_i[11]B1[37]B3[37]B5[37]B7[37]B9[37]B11[37]B13[37]B15[37]
LC_i[12]B1[38]B3[38]B5[38]B7[38]B9[38]B11[38]B13[38]B15[38]
LC_i[13]B1[39]B3[39]B5[39]B7[39]B9[39]B11[39]B13[39]B15[39]
LC_i[14]B1[40]B3[40]B5[40]B7[40]B9[40]B11[40]B13[40]B15[40]
LC_i[15]B1[41]B3[41]B5[41]B7[41]B9[41]B11[41]B13[41]B15[41]
LC_i[16]B1[42]B3[42]B5[42]B7[42]B9[42]B11[42]B13[42]B15[42]
LC_i[17]B1[43]B3[43]B5[43]B7[43]B9[43]B11[43]B13[43]B15[43]
LC_i[18]B1[44]B3[44]B5[44]B7[44]B9[44]B11[44]B13[44]B15[44]
LC_i[19]B1[45]B3[45]B5[45]B7[45]B9[45]B11[45]B13[45]B15[45]
- -

-LC_i[8] is the CarryEnable bit. This bit must be set if the carry logic is used. -

- -

-LC_i[9] is the DffEnable bit. It enables the output flip-flop for the LUT. -

- -

-LC_i[18] is the Set_NoReset bit. When this bit is set then the set/reset signal will set, not reset the flip-flop. -

- -

-LC_i[19] is the AsyncSetReset bit. When this bit is set then the set/reset signal is asynchronous to the clock. -

- -

-The LUT implements the following truth table: -

- - - - - - - - - - - - - - - - - - - -
in_3in_2in_1in_0lout
0000LC_i[4]
0001LC_i[14]
0010LC_i[15]
0011LC_i[5]
0100LC_i[6]
0101LC_i[16]
0110LC_i[17]
0111LC_i[7]
1000LC_i[3]
1001LC_i[13]
1010LC_i[12]
1011LC_i[2]
1100LC_i[1]
1101LC_i[11]
1110LC_i[10]
1111LC_i[0]
- -

-LUT inputs that are not connected to anything are driven low. The set/reset -signal is also driven low if not connected to any other driver, and the clock -enable signal is driven high when left unconnected. -

- - diff --git a/docs/notes_osx.html b/docs/notes_osx.html deleted file mode 100644 index 5ff65fb..0000000 --- a/docs/notes_osx.html +++ /dev/null @@ -1,84 +0,0 @@ - - -Project IceStorm – Notes for Installing on OSX - -

Project IceStorm – Notes for Installing on OSX

- -

-The toolchain should be easy to install on OSX platforms. Below are a few troubleshooting items found on Mountain Lion (10.8.2). -

- -

-See https://github.com/ddm/icetools for a set of shell scripts to build IceStorm on OSX (using brew for dependencies). -

- -

Installing FTDI Library

- -

-The libftdi package (.so lib binary and the ftdi.h header) has been renamed to libftdi0, so either do: -

- - - -

iceprog make error on "ftdi.h not found"

- -

-Note that Mac Ports installs to /opt instead of /usr, so change the first two lines in iceprog/Makefile to: -

- -
-LDLIBS = -L/usr/local/lib -L/opt/local/lib -lftdi -lm
-CFLAGS = -MD -O0 -ggdb -Wall -std=c99 -I/usr/local/include -I/opt/local/include/
-
- -

-Basically you are indicating where to find the lib with -L/opt/local/lib and where to find the .h with -I/opt/local/include/. -

- -

yosys make error on "<tuple> not found"

- -

-This is a compiler issue, i.e., you are probably running on clang and you can circumvent this error by compiling against another compiler. -Edit the Makefile of yosys and replace the two first lines for this, i.e., comment the first line (clang) and uncomment the second (gcc): -

- -
-#CONFIG := clang
-CONFIG := gcc
-
- -

error "Can't find iCE FTDI USB device (vendor_id 0x0403, device_id 0x6010)." while uploading code to FPGA (e.g., "iceprog example.bin")

- -

-You need to unload the FTDI driver (notes below are from Mountain Lion, 10.8.2). -First check if it is running: -

- -
-kextstat | grep FTDIUSBSerialDriver
-
- -

-If you see it on the kextstat, we need to unload it: -

- -
-sudo kextunload -b com.FTDI.driver.FTDIUSBSerialDriver
-
- -

-Repeat the kextstat command and check that the driver was successfully unloaded. -

- -

-Try running iceprog example.bin again. It should be working now. -

- -

-Note: On newer OSes perhaps you need to also kextunload the com.apple.driver.AppleUSBFTDI driver. -

- diff --git a/docs/ram_tile.html b/docs/ram_tile.html deleted file mode 100644 index 2264966..0000000 --- a/docs/ram_tile.html +++ /dev/null @@ -1,104 +0,0 @@ - - - -Project IceStorm – RAM Tile Documentation - -

Project IceStorm – RAM Tile Documentation

- -

-Project IceStorm aims at documenting the bitstream format of Lattice iCE40 -FPGAs and providing simple tools for analyzing and creating bitstream files. -This is work in progress. -

- -

Span-4 and Span-12 Wires

- -

-Regarding the Span-4 and Span-12 Wires a RAM tile behaves exactly like a LOGIC tile. So for simple -applications that do not need the block ram resources, the RAM tiles can be handled like a LOGIC -tiles without logic cells in them. -

- -

Block RAM Resources

- -

-A pair or RAM tiles (odd and even y-coordinates) provides an interface to a block ram cell. Like with -LOGIC tiles, signals entering the RAM tile have to be routed over local tracks to the block ram -inputs. Tiles with odd y-coordinates are "bottom" RAM Tiles (RAMB Tiles), and tiles with even y-coordinates -are "top" RAM Tiles (RAMT Tiles). Each pair of RAMB/RAMT tiles implements a SB_RAM40_4K cell. The -cell ports are spread out over the two tiles as follows: -

- - - - - - - - - - - - - - -
SB_RAM40_4KRAMB TileRAMT Tile
RDATA[15:0]RDATA[7:0]RDATA[15:8]
RADDR[10:0]-RADDR[10:0]
WADDR[10:0]WADDR[10:0]-
MASK[15:0]MASK[7:0]MASK[15:8]
WDATA[15:0]WDATA[7:0]WDATA[15:8]
RCLKE-RCLKE
RCLK-RCLK
RE-RE
WCLKEWCLKE-
WCLKWCLK-
WEWE-
- -

-The configuration bit RamConfig PowerUp in the RAMB tile enables the memory. This bit -is active-low in 1k chips, i.e. an unused RAM block has only this bit set. Note that icebox_explain.py -will ignore all RAMB tiles that only have the RamConfig PowerUp bit set. -

- -

-In 8k chips the RamConfig PowerUp bit is active-high. So an unused RAM block has all bits cleared -in the 8k config bitstream. -

- -

-The RamConfig CBIT_* bits in the RAMT tile configure the read/write width of the -memory. Those bits map to the SB_RAM40_4K cell parameters as follows: -

- - - - - - - -
SB_RAM40_4KRAMT Config Bit
WRITE_MODE[0]RamConfig CBIT_0
WRITE_MODE[1]RamConfig CBIT_1
READ_MODE[0]RamConfig CBIT_2
READ_MODE[1]RamConfig CBIT_3
- -

-The read/write mode selects the width of the read/write port: -

- - - - - - - -
MODEDATA WidthUsed WDATA/RDATA Bits
01615, 14, 13, 12, 11, 10, 9, 8, 7, 6, 5, 4, 3, 2, 1, 0
1814, 12, 10, 8, 6, 4, 2, 0
2413, 9, 5, 1
3211, 3
- -

-The NegClk bit in the RAMB tile (1k die) or RAMT tile (other devices) negates the polarity of the WCLK port, -and the NegClk bit in the RAMT (1k die) or RAMB tile (other devices) tile negates the polarity of the RCLK port. -

- -

-A logic tile sends the output of its eight logic cells to its neighbour tiles. A RAM tile does the same thing -with the RDATA outputs. Each RAMB tile exports its RDATA[7:0] outputs and each RAMT tile -exports its RDATA[15:8] outputs via this mechanism. -

- - diff --git a/docs/checkerboard.png b/docs/source/_static/images/checkerboard.png similarity index 100% rename from docs/checkerboard.png rename to docs/source/_static/images/checkerboard.png diff --git a/docs/checkerboard.sh b/docs/source/_static/images/checkerboard.sh similarity index 100% rename from docs/checkerboard.sh rename to docs/source/_static/images/checkerboard.sh diff --git a/docs/colbuf.svg b/docs/source/_static/images/colbuf.svg similarity index 100% rename from docs/colbuf.svg rename to docs/source/_static/images/colbuf.svg diff --git a/docs/iosp.svg b/docs/source/_static/images/iosp.svg similarity index 100% rename from docs/iosp.svg rename to docs/source/_static/images/iosp.svg diff --git a/docs/sp4h.svg b/docs/source/_static/images/sp4h.svg similarity index 100% rename from docs/sp4h.svg rename to docs/source/_static/images/sp4h.svg diff --git a/docs/sp4v.svg b/docs/source/_static/images/sp4v.svg similarity index 100% rename from docs/sp4v.svg rename to docs/source/_static/images/sp4v.svg diff --git a/docs/source/conf.py b/docs/source/conf.py new file mode 100644 index 0000000..6036d28 --- /dev/null +++ b/docs/source/conf.py @@ -0,0 +1,33 @@ +# 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 Icestorm' +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/format.rst b/docs/source/format.rst new file mode 100644 index 0000000..4f88ae9 --- /dev/null +++ b/docs/source/format.rst @@ -0,0 +1,154 @@ +Bitstream File Format Documentation +=================================== + +General Description of the File Format +-------------------------------------- + +The bitstream file starts with the bytes 0xFF 0x00, followed by a +sequence of zero-terminated comment strings, followed by 0x00 0xFF. +However, there seems to be a bug in the Lattice "bitstream" tool that +moves the terminating 0x00 0xFF a few bytes into the comment string in +some cases. + +After the comment sections the token 0x7EAA997E (MSB first) starts the +actual bit stream. The bitstream consists of one-byte commands, followed +by a payload word, followed by an optional block of data. The MSB nibble +of the command byte is the command opcode, the LSB nibble is the length +of the command payload in bytes. The commands that do not require a +payload are using the opcode 0, with the command encoded in the payload +field. Note that this "payload" in this context refers to a single +integer argument, not the blocks of data that follows the command in +case of the CRAM and BRAM commands. + +The following commands are known: + ++-----------------------------------+-----------------------------------+ +| Opcode | Description | ++===================================+===================================+ +| 0 | payload=1: Write CRAM Data | +| | payload=2: Read BRAM Data | +| | payload=3: Write BRAM Data | +| | payload=4: Read BRAM Data | +| | payload=5: Reset CRC | +| | payload=6: Wakeup | +| | payload=8: Reboot | ++-----------------------------------+-----------------------------------+ +| 1 | Set bank number | ++-----------------------------------+-----------------------------------+ +| 2 | CRC check | ++-----------------------------------+-----------------------------------+ +| 4 | Set boot address | ++-----------------------------------+-----------------------------------+ +| 5 | Set internal oscillator frequency | +| | range | +| | payload=0: low | +| | payload=1: medium | +| | payload=2: high | ++-----------------------------------+-----------------------------------+ +| 6 | Set bank width (16-bits, MSB | +| | first) | ++-----------------------------------+-----------------------------------+ +| 7 | Set bank height (16-bits, MSB | +| | first) | ++-----------------------------------+-----------------------------------+ +| 8 | Set bank offset (16-bits, MSB | +| | first) | ++-----------------------------------+-----------------------------------+ +| 9 | payload=0: Disable warm boot | +| | payload=16: Enable cold boot | +| | payload=32: Enable warm boot | ++-----------------------------------+-----------------------------------+ + +Use iceunpack -vv to display the commands as they are interpreted by the +tool. + +Note: The format itself seems to be very flexible. At the moment it is +unclear what the FPGA devices will do when presented with a bitstream +that use the commands in a different way than the bitstreams generated +by the lattice tools. + +Writing SRAM content +-------------------- + +Most bytes in the bitstream are SRAM data bytes that should be written +to the various SRAM banks in the FPGA. The following sequence is used to +program an SRAM cell: + +- Set bank width (opcode 6) +- Set bank height (opcode 7) +- Set bank offset (opcode 8) +- Set bank number (opcode 1) +- CRAM or BRAM Data Command +- (width \* height / 8) data bytes +- two zero bytes + +The bank width and height parameters reflect the width and height of the +SRAM bank. A large SRAM can be written in smaller chunks. In this case +height parameter may be smaller and the offset parameter reflects the +vertical start position. + +There are four CRAM and four BRAM banks in an iCE40 FPGA. The different +devices from the family use different widths and heights, but the same +number of banks. + +The CRAM banks hold the configuration bits for the FPGA fabric and hard +IP blocks, the BRAM corresponds to the contents of the block ram +resources. + +The ordering of the data bits is in MSB first row-major order. + +Organization of the CRAM +------------------------ + +|Mapping of tile config bits to 2D CRAM| + +The chip is organized into four quadrants. Each CRAM memory bank +contains the configuration bits for one quadrant. The address 0 is +always the corner of the quadrant, i.e. in one quadrant the bit +addresses increase with the tile x/y coordinates, in another they +increase with the tile x coordinate but decrease with the tile y +coordinate, and so on. + +For an iCE40 1k device, that has 12 x 16 tiles (not counting the io +tiles), the CRAM bank 0 is the one containing the corner tile (1 1), the +CRAM bank 1 contains the corner tile (1 16), the CRAM bank 2 contains +the corner tile (12 1) and the CRAM bank 3 contains the corner tile (12 +16). The entire CRAM of such a device is depicted on the right (bank 0 +is in the lower left corner in blue/green). + +The checkerboard pattern in the picture visualizes which bits are +associated with which tile. The height of the configuration block is 16 +for all tile types, but the width is different for each tile type. IO +tiles have configurations that are 18 bits wide, LOGIC tiles are 54 bits +wide, and RAM tiles are 42 bits wide. (Notice the two slightly smaller +columns for the RAM tiles.) + +The IO tiles on the top and bottom of the chip use a strange permutation +pattern for their bits. It can be seen in the picture that their columns +are spread out horizontally. What cannot be seen in the picture is the +columns also are not in order and the bit positions are vertically +permuted as well. The CramIndexConverter class in icepack.cc +encapsulates the calculations that are necessary to convert between +tile-relative bit addresses and CRAM bank-relative bit addresses. + +The black pixels in the image correspond to CRAM bits that are not +associated with any IO, LOGIC or RAM tile. Some of them are unused, +others are used by hard IPs or other global resources. The iceunpack +tool reports such bits, when set, with the ".extra_bit bank x y" +statement in the ASCII output format. + +Organization of the BRAM +------------------------ + +This part of the documentation has not been written yet. + +CRC Check +--------- + +The CRC is a 16 bit CRC. The (truncated) polynomial is 0x1021 +(CRC-16-CCITT). The "Reset CRC" command sets the CRC to 0xFFFF. No zero +padding is performed. + +.. |Mapping of tile config bits to 2D CRAM| image:: _static/images/checkerboard.png + :height: 200px + :target: checkerboard.png diff --git a/docs/source/index.rst b/docs/source/index.rst new file mode 100644 index 0000000..846000d --- /dev/null +++ b/docs/source/index.rst @@ -0,0 +1,14 @@ +Welcome to Project Icestorm +=========================== + +.. toctree:: + :maxdepth: 2 + :caption: Project Icestorm + + overview + format + logic_tile + io_tile + ram_tile + ultraplus + notes_osx diff --git a/docs/source/io_tile.rst b/docs/source/io_tile.rst new file mode 100644 index 0000000..12d09b6 --- /dev/null +++ b/docs/source/io_tile.rst @@ -0,0 +1,464 @@ +IO Tile Documentation +===================== + +Span-4 and Span-12 Wires +------------------------ + +|IO Tile Span-Wires| + +The image on the right shows the span-wires of a left (or right) io cell +(click to enlarge). + +A left/right io cell has 16 connections named span4_vert_t_0 to +span4_vert_t_15 on its top edge and 16 connections named span4_vert_b_0 +to span4_vert_b_15 on its bottom edge. The nets span4_vert_t_0 to +span4_vert_t_11 are connected to span4_vert_b_4 to span4_vert_b_15. The +span-4 and span-12 wires of the adjacent logic cell are connected to the +nets span4_horz_0 to span4_horz_47 and span12_horz_0 to span12_horz_23. + +A top/bottom io cell has 16 connections named span4_horz_l_0 to +span4_horz_l_15 on its left edge and 16 connections named span4_horz_r_0 +to span4_horz_r_15 on its right edge. The nets span4_horz_l_0 to +span4_horz_l_11 are connected to span4_horz_r_4 to span4_horz_r_15. The +span-4 and span-12 wires of the adjacent logic cell are connected to the +nets span4_vert_0 to span4_vert_47 and span12_vert_0 to span12_vert_23. + +The vertical span4 wires of left/right io cells are connected "around +the corner" to the horizontal span4 wires of the top/bottom io cells. +For example span4_vert_b_0 of IO cell (0 1) is connected to +span4_horz_l_0 (span4_horz_r_4) of IO cell (1 0). + +Note that unlike the span-wires connection LOGIC and RAM tiles, the +span-wires connecting IO tiles to each other are not pairwise crossed +out. + +IO Blocks +--------- + +Each IO tile contains two IO blocks. Each IO block essentially +implements the SB_IO primitive from the Lattice iCE Technology Library. +Some inputs are shared between the two IO blocks. The following table +lists how the wires in the logic tile map to the SB_IO primitive ports: + +================= ================ ============ +SB_IO Port IO Block 0 IO Block 1 +================= ================ ============ +D_IN_0 io_0/D_IN_0 io_1/D_IN_0 +D_IN_1 io_0/D_IN_1 io_1/D_IN_1 +D_OUT_0 io_0/D_OUT_0 io_1/D_OUT_0 +D_OUT_1 io_0/D_OUT_1 io_1/D_OUT_1 +OUTPUT_ENABLE io_0/OUT_ENB io_1/OUT_ENB +CLOCK_ENABLE io_global/cen +INPUT_CLK io_global/inclk +OUTPUT_CLK io_global/outclk +LATCH_INPUT_VALUE io_global/latch +================= ================ ============ + +Like the inputs to logic cells, the inputs to IO blocks are routed to +the IO block via a two-stage process. A signal is first routed to one of +16 local tracks in the IO tile and then from the local track to the IO +block. + +The io_global/latch signal is shared among all IO tiles on an edge of +the chip and is driven by fabout from one dedicated IO tile on that +edge. For the HX1K chips the tiles driving the io_global/latch signal +are: (0, 7), (13, 10), (5, 0), and (8, 17) + +A logic tile sends the output of its eight logic cells to its neighbour +tiles. An IO tile does the same thing with the four D_IN signals created +by its two IO blocks. The D_IN signals map to logic function indices as +follows: + +============== =========== +Function Index D_IN Wire +============== =========== +0 io_0/D_IN_0 +1 io_0/D_IN_1 +2 io_1/D_IN_0 +3 io_1/D_IN_1 +4 io_0/D_IN_0 +5 io_0/D_IN_1 +6 io_1/D_IN_0 +7 io_1/D_IN_1 +============== =========== + +For example the signal io_1/D_IN_0 in IO tile (0, 5) can be seen as +neigh_op_lft_2 and neigh_op_lft_6 in LOGIC tile (1, 5). + +Each IO Tile has 2 NegClk configuration bits, suggesting that the clock +signals can be inverted independently for the the two IO blocks in the +tile. However, the Lattice tools refuse to pack two IO blocks with +different clock polarity into the same IO tile. In our tests we only +managed to either set or clear both NegClk bits. + +Each IO block has two IoCtrl IE bits that enable the input buffers and +two IoCtrl REN bits that enable the pull up resistors. Both bits are +active low, i.e. an unused IO tile will have both IE bits set and both +REN bits cleared (the default behavior is to enable pullup resistors on +all unused pins). Note that icebox_explain.py will ignore all IO tiles +that only have the two IoCtrl IE bits set. + +However, the IoCtrl IE_0/IE_1 and IoCtrl REN_0/REN_1 do not necessarily +configure the IO PIN that are connected to the IO block in the same +tile, and if they do the numbers (0/1) do not necessarily match. As a +general rule, the pins on the right and bottom side of the chips match +up with the IO blocks and for the pins on the left and top side the +numbers must be swapped. But in some cases the IO block and the set of +IE/REN are not even located in the same tile. The following table lists +the correlation between IO blocks and IE/REN bits for the 1K chip: + +======== ============ +IO Block IE/REN Block +======== ============ +0 14 1 0 14 0 +0 14 0 0 14 1 +0 13 1 0 13 0 +0 13 0 0 13 1 +0 12 1 0 12 0 +0 12 0 0 12 1 +0 11 1 0 11 0 +0 11 0 0 11 1 +0 10 1 0 10 0 +0 10 0 0 10 1 +0 9 1 0 9 0 +0 9 0 0 9 1 +0 8 1 0 8 0 +0 8 0 0 8 1 +0 6 1 0 6 0 +0 6 0 0 6 1 +0 5 1 0 5 0 +0 5 0 0 5 1 +0 4 1 0 4 0 +0 4 0 0 4 1 +0 3 1 0 3 0 +0 3 0 0 3 1 +0 2 1 0 2 0 +0 2 0 0 2 1 +======== ============ + +======== ============ +IO Block IE/REN Block +======== ============ +1 0 0 1 0 0 +1 0 1 1 0 1 +2 0 0 2 0 0 +2 0 1 2 0 1 +3 0 0 3 0 0 +3 0 1 3 0 1 +4 0 0 4 0 0 +4 0 1 4 0 1 +5 0 0 5 0 0 +5 0 1 5 0 1 +6 0 1 6 0 0 +7 0 0 6 0 1 +6 0 0 7 0 0 +7 0 1 7 0 1 +8 0 0 8 0 0 +8 0 1 8 0 1 +9 0 0 9 0 0 +9 0 1 9 0 1 +10 0 0 10 0 0 +10 0 1 10 0 1 +11 0 0 11 0 0 +11 0 1 11 0 1 +12 0 0 12 0 0 +12 0 1 12 0 1 +======== ============ + +======== ============ +IO Block IE/REN Block +======== ============ +13 1 0 13 1 0 +13 1 1 13 1 1 +13 2 0 13 2 0 +13 2 1 13 2 1 +13 3 1 13 3 1 +13 4 0 13 4 0 +13 4 1 13 4 1 +13 6 0 13 6 0 +13 6 1 13 6 1 +13 7 0 13 7 0 +13 7 1 13 7 1 +13 8 0 13 8 0 +13 8 1 13 8 1 +13 9 0 13 9 0 +13 9 1 13 9 1 +13 11 0 13 10 0 +13 11 1 13 10 1 +13 12 0 13 11 0 +13 12 1 13 11 1 +13 13 0 13 13 0 +13 13 1 13 13 1 +13 14 0 13 14 0 +13 14 1 13 14 1 +13 15 0 13 15 0 +13 15 1 13 15 1 +======== ============ + +======== ============ +IO Block IE/REN Block +======== ============ +12 17 1 12 17 1 +12 17 0 12 17 0 +11 17 1 11 17 1 +11 17 0 11 17 0 +10 17 1 9 17 1 +10 17 0 9 17 0 +9 17 1 10 17 1 +9 17 0 10 17 0 +8 17 1 8 17 1 +8 17 0 8 17 0 +7 17 1 7 17 1 +7 17 0 7 17 0 +6 17 1 6 17 1 +5 17 1 5 17 1 +5 17 0 5 17 0 +4 17 1 4 17 1 +4 17 0 4 17 0 +3 17 1 3 17 1 +3 17 0 3 17 0 +2 17 1 2 17 1 +2 17 0 2 17 0 +1 17 1 1 17 1 +1 17 0 1 17 0 +======== ============ + +When an input pin pair is used as LVDS pair (IO standard SB_LVDS_INPUT, +bank 3 / left edge only), then the four bits IoCtrl IE_0/IE_1 and IoCtrl +REN_0/REN_1 are all set, as well as the IoCtrl LVDS bit. + +In the iCE 8k devices the IoCtrl IE bits are active high. So an unused +IO tile on an 8k chip has all bits cleared. + +Global Nets +----------- + +iCE40 FPGAs have 8 global nets. Each global net can be driven directly +from an IO pin. In the FPGA bitstream, routing of external signals to +global nets is not controlled by bits in the IO tile. Instead bits that +do not belong to any tile are used. In IceBox nomenclature such bits are +called "extra bits". + +The following table lists which pins / IO blocks may be used to drive +which global net, and what .extra statements in the IceStorm ASCII file +format to represent the corresponding configuration bits: + ++-----------------+-----------------+-----------------+-----------------+ +| Glb Net | Pin | IO Tile + | IceBox | +| | (HX1K-TQ144) | Block # | Statement | ++=================+=================+=================+=================+ +| 0 | 93 | 13 8 1 | .extra_bit 0 | +| | | | 330 142 | ++-----------------+-----------------+-----------------+-----------------+ +| 1 | 21 | 0 8 1 | .extra_bit 0 | +| | | | 331 142 | ++-----------------+-----------------+-----------------+-----------------+ +| 2 | 128 | 7 17 0 | .extra_bit 1 | +| | | | 330 143 | ++-----------------+-----------------+-----------------+-----------------+ +| 3 | 50 | 7 0 0 | .extra_bit 1 | +| | | | 331 143 | ++-----------------+-----------------+-----------------+-----------------+ +| 4 | 20 | 0 9 0 | .extra_bit 1 | +| | | | 330 142 | ++-----------------+-----------------+-----------------+-----------------+ +| 5 | 94 | 13 9 0 | .extra_bit 1 | +| | | | 331 142 | ++-----------------+-----------------+-----------------+-----------------+ +| 6 | 49 | 6 0 1 | .extra_bit 0 | +| | | | 330 143 | ++-----------------+-----------------+-----------------+-----------------+ +| 7 | 129 | 6 17 1 | .extra_bit 0 | +| | | | 331 143 | ++-----------------+-----------------+-----------------+-----------------+ + +Signals internal to the FPGA can also be routed to the global nets. This +is done by routing the signal to the fabout net on an IO tile. The same +set of I/O tiles is used for this, but in this case each of the I/O +tiles corresponds to a different global net: + +======= === ==== ==== === ==== === === ==== +Glb Net 0 1 2 3 4 5 6 7 +IO Tile 7 0 7 17 13 9 0 9 6 17 6 0 0 8 13 8 +======= === ==== ==== === ==== === === ==== + +|Column Buffers| + +Column Buffer Control Bits +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Each LOGIC, IO, and RAMB tile has 8 ColBufCtrl bits, one for each global +net. In most tiles this bits have no function, but in tiles in rows 4, +5, 12, and 13 (for RAM columns: rows 3, 5, 11, and 13) this bits control +which global nets are driven to the column of tiles below and/or above +that tile (including that tile), as illustrated in the image to the +right (click to enlarge). + +In 8k chips the rows 8, 9, 24, and 25 contain the column buffers. 8k +RAMB and RAMT tiles can control column buffers, so the pattern looks the +same for RAM, LOGIC, and IO columns. + +Warmboot +-------- + +The SB_WARMBOOT primitive in iCE40 FPGAs has three inputs and no +outputs. The three inputs of that cell are driven by the fabout signal +from three IO tiles. In HX1K chips the tiles connected to the +SB_WARMBOOT primitive are: + +============ ======= +Warmboot Pin IO Tile +============ ======= +BOOT 12 0 +S0 13 1 +S1 13 2 +============ ======= + +PLL Cores +--------- + +The PLL primitives in iCE40 FPGAs are configured using the PLLCONFIG\_\* +bits in the IO tiles. The configuration for a single PLL cell is spread +out over many IO tiles. For example, the PLL cell in the 1K chip are +configured as follows (bits listed from LSB to MSB): + ++-----------------------+-----------------------+-----------------------+ +| IO Tile | Config Bit | SB_PLL40\_\* | +| | | Parameter | ++=======================+=======================+=======================+ +| 0 3 | PLLCONFIG_5 | Select PLL Type: | +| | | 000 = DISABLED | +| | | 010 = SB_PLL40_PAD | +| | | 100 = SB_PLL40_2_PAD | +| | | 110 = SB_PLL40_2F_PAD | +| | | 011 = SB_PLL40_CORE | +| | | 111 = | +| | | SB_PLL40_2F_CORE | ++-----------------------+-----------------------+-----------------------+ +| 0 5 | PLLCONFIG_1 | | ++-----------------------+-----------------------+-----------------------+ +| 0 5 | PLLCONFIG_3 | | ++-----------------------+-----------------------+-----------------------+ +| 0 5 | PLLCONFIG_5 | FEEDBACK_PATH | +| | | 000 = "DELAY" | +| | | 001 = "SIMPLE" | +| | | 010 = | +| | | "PHASE_AND_DELAY" | +| | | 110 = "EXTERNAL" | ++-----------------------+-----------------------+-----------------------+ +| 0 2 | PLLCONFIG_9 | | ++-----------------------+-----------------------+-----------------------+ +| 0 3 | PLLCONFIG_1 | | ++-----------------------+-----------------------+-----------------------+ +| 0 4 | PLLCONFIG_4 | DELAY_ADJ | +| | | USTMENT_MODE_FEEDBACK | +| | | 0 = "FIXED" | +| | | 1 = "DYNAMIC" | ++-----------------------+-----------------------+-----------------------+ +| 0 4 | PLLCONFIG_9 | DELAY_ADJ | +| | | USTMENT_MODE_RELATIVE | +| | | 0 = "FIXED" | +| | | 1 = "DYNAMIC" | ++-----------------------+-----------------------+-----------------------+ +| 0 3 | PLLCONFIG_6 | PLLOUT_SELECT | +| | | PLLOUT_SELECT_PORTA | +| | | 00 = "GENCLK" | +| | | 01 = "GENCLK_HALF" | +| | | 10 = "SHIFTREG_90deg" | +| | | 11 = "SHIFTREG_0deg" | ++-----------------------+-----------------------+-----------------------+ +| 0 3 | PLLCONFIG_7 | | ++-----------------------+-----------------------+-----------------------+ +| 0 3 | PLLCONFIG_2 | PLLOUT_SELECT_PORTB | +| | | 00 = "GENCLK" | +| | | 01 = "GENCLK_HALF" | +| | | 10 = "SHIFTREG_90deg" | +| | | 11 = "SHIFTREG_0deg" | ++-----------------------+-----------------------+-----------------------+ +| 0 3 | PLLCONFIG_3 | | ++-----------------------+-----------------------+-----------------------+ +| 0 3 | PLLCONFIG_4 | SHIFTREG_DIV_MODE | ++-----------------------+-----------------------+-----------------------+ +| 0 3 | PLLCONFIG_8 | TEST_MODE | ++-----------------------+-----------------------+-----------------------+ +| 0 5 | PLLCONFIG_2 | Enable ICEGATE for | +| | | PLLOUTGLOBALA | ++-----------------------+-----------------------+-----------------------+ +| 0 5 | PLLCONFIG_4 | Enable ICEGATE for | +| | | PLLOUTGLOBALB | ++-----------------------+-----------------------+-----------------------+ + +======= =========== ====================== +IO Tile Config Bit SB_PLL40\_\* Parameter +======= =========== ====================== +0 3 PLLCONFIG_9 FDA_FEEDBACK +0 4 PLLCONFIG_1 +0 4 PLLCONFIG_2 +0 4 PLLCONFIG_3 +0 5 PLLCONFIG_5 FDA_RELATIVE +0 4 PLLCONFIG_6 +0 4 PLLCONFIG_7 +0 4 PLLCONFIG_8 +0 1 PLLCONFIG_1 DIVR +0 1 PLLCONFIG_2 +0 1 PLLCONFIG_3 +0 1 PLLCONFIG_4 +0 1 PLLCONFIG_5 DIVF +0 1 PLLCONFIG_6 +0 1 PLLCONFIG_7 +0 1 PLLCONFIG_8 +0 1 PLLCONFIG_9 +0 2 PLLCONFIG_1 +0 2 PLLCONFIG_2 +0 2 PLLCONFIG_3 DIVQ +0 2 PLLCONFIG_4 +0 2 PLLCONFIG_5 +0 2 PLLCONFIG_6 FILTER_RANGE +0 2 PLLCONFIG_7 +0 2 PLLCONFIG_8 +======= =========== ====================== + +The PLL inputs are routed to the PLL via the fabout signal from various +IO tiles. The non-clock PLL outputs are routed via otherwise unused +neigh_op\_\* signals in fabric corners. For example in case of the 1k +chip: + +==== ============== ====================== +Tile Net-Segment SB_PLL40\_\* Port Name +==== ============== ====================== +0 1 fabout REFERENCECLK +0 2 fabout EXTFEEDBACK +0 4 fabout DYNAMICDELAY +0 5 fabout +0 6 fabout +0 10 fabout +0 11 fabout +0 12 fabout +0 13 fabout +0 14 fabout +1 1 neigh_op_bnl_1 LOCK +1 0 fabout BYPASS +2 0 fabout RESETB +5 0 fabout LATCHINPUTVALUE +12 1 neigh_op_bnr_3 SDO +4 0 fabout SDI +3 0 fabout SCLK +==== ============== ====================== + +The PLL clock outputs are fed directly into the input path of certain IO +tiles. In case of the 1k chip the PORTA clock is fed into PIO 1 of IO +Tile (6 0) and the PORTB clock is fed into PIO 0 of IO Tile (7 0). +Because of this, those two PIOs can only be used as output Pins by the +FPGA fabric when the PLL ports are being used. + +The input path that are stolen are also used to implement the ICEGATE +function. If the input pin type of the input path being stolen is set to +PIN_INPUT_LATCH, then the ICEGATE function is enabled for the +corresponding CORE output of the PLL. + +.. |IO Tile Span-Wires| image:: _static/images/iosp.svg + :height: 200px + :target: iosp.svg +.. |Column Buffers| image:: _static/images/colbuf.svg + :height: 200px + :target: colbuf.svg diff --git a/docs/source/logic_tile.rst b/docs/source/logic_tile.rst new file mode 100644 index 0000000..9a6f23c --- /dev/null +++ b/docs/source/logic_tile.rst @@ -0,0 +1,327 @@ +LOGIC Tile Documentation +======================== + +Span-4 and Span-12 Wires +------------------------ + +The *span-4* and *span-12* wires are the main interconnect resource in +iCE40 FPGAs. They "span" (have a length of) 4 or 12 cells in horizontal +or vertical direction. + +All routing resources in iCE40 are directional tristate buffers. The +bits marked routing use the all-zeros config pattern for tristate, while +the bits marked buffer have a dedicated buffer-enable bit, which is 1 in +all non-tristate configurations. + +Span-4 Horizontal +~~~~~~~~~~~~~~~~~ + +|Span-4 Horizontal| + +The image on the right shows the *horizontal span-4* wires of a logic or +ram cell (click to enlarge). + +On the left side of the cell there are 48 connections named sp4_h_l_0 to +sp4_h_l_47. The lower 36 of those wires are connected to sp4_h_r_12 to +sp4_h_r_47 on the right side of the cell. (IceStorm normalizes this wire +names to sp4_h_r_0 to sp4_h_r_35. Note: the Lattice tools use a +different normalization scheme for this wire names.) The wires +connecting the left and right horizontal span-4 ports are pairwise +crossed-out. + +The wires sp4_h_l_36 to sp4_h_l_47 terminate in the cell as do the wires +sp4_h_r_0 to sp4_h_r_11. + +This wires "span" 4 cells, i.e. they connect 5 cells if you count the +cells on both ends of the wire. + +For example, the wire sp4_h_r_0 in cell (x, y) has the following names: + +================ ===================== ===================== +Cell Coordinates sp4_h_l\_\* wire name sp4_h_r\_\* wire name +================ ===================== ===================== +x, y -- sp4_h_r_0 +x+1, y sp4_h_l_0 sp4_h_r_13 +x+2, y sp4_h_l_13 sp4_h_r_24 +x+3, y sp4_h_l_24 sp4_h_r_37 +x+4, y sp4_h_l_37 -- +================ ===================== ===================== + +Span-4 Vertical +~~~~~~~~~~~~~~~ + +|Span-4 Vertical| + +The image on the right shows the *vertical span-4* wires of a logic or +ram cell (click to enlarge). + +Similar to the horizontal span-4 wires there are 48 connections on the +top (sp4_v_t_0 to sp4_v_t_47) and 48 connections on the bottom +(sp4_v_b_0 to sp4_v_b_47). The wires sp4_v_t_0 to sp4_v_t_35 are +connected to sp4_v_b_12 to sp4_v_b_47 (with pairwise crossing out). Wire +names are normalized to sp4_v_b_12 to sp4_v_b_47. + +But in addition to that, each cell also has access to sp4_v_b_0 to +sp4_v_b_47 of its right neighbour. This are the wires sp4_r_v_b_0 to +sp4_r_v_b_47. So over all a single vertical span-4 wire connects 9 +cells. For example, the wire sp4_v_b_0 in cell (x, y) has the following +names: + ++----------------+----------------+----------------+----------------+ +| Cell | sp4_v_t\_\* | sp4_v_b\_\* | sp4_r_v_b\_\* | +| Coordinates | wire name | wire name | wire name | ++================+================+================+================+ +| x, y | -- | sp4_v_b_0 | -- | ++----------------+----------------+----------------+----------------+ +| x, y-1 | sp4_v_t_0 | sp4_v_b_13 | -- | ++----------------+----------------+----------------+----------------+ +| x, y-2 | sp4_v_t_13 | sp4_v_b_24 | -- | ++----------------+----------------+----------------+----------------+ +| x, y-3 | sp4_v_t_24 | sp4_v_b_37 | -- | ++----------------+----------------+----------------+----------------+ +| x, y-4 | sp4_v_t_37 | -- | -- | ++----------------+----------------+----------------+----------------+ +| x-1, y | -- | -- | sp4_r_v_b_0 | ++----------------+----------------+----------------+----------------+ +| x-1, y-1 | -- | -- | sp4_r_v_b_13 | ++----------------+----------------+----------------+----------------+ +| x-1, y-2 | -- | -- | sp4_r_v_b_24 | ++----------------+----------------+----------------+----------------+ +| x-1, y-3 | -- | -- | sp4_r_v_b_37 | ++----------------+----------------+----------------+----------------+ + +Span-12 Horizontal and Vertical +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Similar to the span-4 wires there are also longer horizontal and +vertical span-12 wires. + +There are 24 connections sp12_v_t_0 to sp12_v_t_23 on the top of the +cell and 24 connections sp12_v_b_0 to sp12_v_b_23 on the bottom of the +cell. The wires sp12_v_t_0 to sp12_v_t_21 are connected to sp12_v_b_2 to +sp12_v_b_23 (with pairwise crossing out). The connections sp12_v_b_0, +sp12_v_b_1, sp12_v_t_22, and sp12_v_t_23 terminate in the cell. Wire +names are normalized to sp12_v_b_2 to sp12_v_b_23. + +There are also 24 connections sp12_h_l_0 to sp12_h_l_23 on the left of +the cell and 24 connections sp12_h_r_0 to sp12_h_r_23 on the right of +the cell. The wires sp12_h_l_0 to sp12_h_l_21 are connected to +sp12_h_r_2 to sp12_h_r_23 (with pairwise crossing out). The connections +sp12_h_r_0, sp12_h_r_1, sp12_h_l_22, and sp12_h_l_23 terminate in the +cell. Wire names are normalized to sp12_v_r_2 to sp12_h_r_23. + +Local Tracks +------------ + +The *local tracks* are the gateway to the logic cell inputs. Signals +from the span-wires and the logic cell outputs of the eight neighbour +cells can be routed to the local tracks and signals from the local +tracks can be routed to the logic cell inputs. + +Each logic tile has 32 local tracks. They are organized in 4 groups of 8 +wires each: local_g0_0 to local_g3_7. + +The span wires, global signals, and neighbour outputs can be routed to +the local tracks. But not all of those signals can be routed to all of +the local tracks. Instead there is a different mix of 16 signals for +each local track. + +The buffer driving the local track has 5 configuration bits. One enable +bit and 4 bits that select the input wire. For example for local_g0_0 +(copy&paste from the bitstream doku): + ++--------+--------+--------+--------+--------+----------+----------------+-----------------+ +| B0[14] | B1[14] | B1[15] | B1[16] | B1[17] | Function | Source-Net | Destination-Net | ++========+========+========+========+========+==========+================+=================+ +| 0 | 0 | 0 | 0 | 1 | buffer | sp4_r_v_b_24 | local_g0_0 | ++--------+--------+--------+--------+--------+----------+----------------+-----------------+ +| 0 | 0 | 0 | 1 | 1 | buffer | sp12_h_r_8 | local_g0_0 | ++--------+--------+--------+--------+--------+----------+----------------+-----------------+ +| 0 | 0 | 1 | 0 | 1 | buffer | neigh_op_bot_0 | local_g0_0 | ++--------+--------+--------+--------+--------+----------+----------------+-----------------+ +| 0 | 0 | 1 | 1 | 1 | buffer | sp4_v_b_16 | local_g0_0 | ++--------+--------+--------+--------+--------+----------+----------------+-----------------+ +| 0 | 1 | 0 | 0 | 1 | buffer | sp4_r_v_b_35 | local_g0_0 | ++--------+--------+--------+--------+--------+----------+----------------+-----------------+ +| 0 | 1 | 0 | 1 | 1 | buffer | sp12_h_r_16 | local_g0_0 | ++--------+--------+--------+--------+--------+----------+----------------+-----------------+ +| 0 | 1 | 1 | 0 | 1 | buffer | neigh_op_top_0 | local_g0_0 | ++--------+--------+--------+--------+--------+----------+----------------+-----------------+ +| 0 | 1 | 1 | 1 | 1 | buffer | sp4_h_r_0 | local_g0_0 | ++--------+--------+--------+--------+--------+----------+----------------+-----------------+ +| 1 | 0 | 0 | 0 | 1 | buffer | lutff_0/out | local_g0_0 | ++--------+--------+--------+--------+--------+----------+----------------+-----------------+ +| 1 | 0 | 0 | 1 | 1 | buffer | sp4_v_b_0 | local_g0_0 | ++--------+--------+--------+--------+--------+----------+----------------+-----------------+ +| 1 | 0 | 1 | 0 | 1 | buffer | neigh_op_lft_0 | local_g0_0 | ++--------+--------+--------+--------+--------+----------+----------------+-----------------+ +| 1 | 0 | 1 | 1 | 1 | buffer | sp4_h_r_8 | local_g0_0 | ++--------+--------+--------+--------+--------+----------+----------------+-----------------+ +| 1 | 1 | 0 | 0 | 1 | buffer | neigh_op_bnr_0 | local_g0_0 | ++--------+--------+--------+--------+--------+----------+----------------+-----------------+ +| 1 | 1 | 0 | 1 | 1 | buffer | sp4_v_b_8 | local_g0_0 | ++--------+--------+--------+--------+--------+----------+----------------+-----------------+ +| 1 | 1 | 1 | 0 | 1 | buffer | sp12_h_r_0 | local_g0_0 | ++--------+--------+--------+--------+--------+----------+----------------+-----------------+ +| 1 | 1 | 1 | 1 | 1 | buffer | sp4_h_r_16 | local_g0_0 | ++--------+--------+--------+--------+--------+----------+----------------+-----------------+ + +Then the signals on the local tracks can be routed to the input pins of +the logic cells. Like before, not every local track can be routed to +every logic cell input pin. Instead there is a different mix of 16 local +track for each logic cell input. For example for lutff_0/in_0: + +====== ====== ====== ====== ====== ======== ========== =============== +B0[26] B1[26] B1[27] B1[28] B1[29] Function Source-Net Destination-Net +====== ====== ====== ====== ====== ======== ========== =============== +0 0 0 0 1 buffer local_g0_0 lutff_0/in_0 +0 0 0 1 1 buffer local_g2_0 lutff_0/in_0 +0 0 1 0 1 buffer local_g1_1 lutff_0/in_0 +0 0 1 1 1 buffer local_g3_1 lutff_0/in_0 +0 1 0 0 1 buffer local_g0_2 lutff_0/in_0 +0 1 0 1 1 buffer local_g2_2 lutff_0/in_0 +0 1 1 0 1 buffer local_g1_3 lutff_0/in_0 +0 1 1 1 1 buffer local_g3_3 lutff_0/in_0 +1 0 0 0 1 buffer local_g0_4 lutff_0/in_0 +1 0 0 1 1 buffer local_g2_4 lutff_0/in_0 +1 0 1 0 1 buffer local_g1_5 lutff_0/in_0 +1 0 1 1 1 buffer local_g3_5 lutff_0/in_0 +1 1 0 0 1 buffer local_g0_6 lutff_0/in_0 +1 1 0 1 1 buffer local_g2_6 lutff_0/in_0 +1 1 1 0 1 buffer local_g1_7 lutff_0/in_0 +1 1 1 1 1 buffer local_g3_7 lutff_0/in_0 +====== ====== ====== ====== ====== ======== ========== =============== + +The 8 global nets on the iCE40 can be routed to the local track via the +glb2local_0 to glb2local_3 nets using a similar two-stage process. The +logic block clock-enable and set-reset inputs can be driven directly +from one of 4 global nets or from one of 4 local tracks. The logic block +clock input can be driven from any of the global nets and from a few +local tracks. See the bitstream documentation for details. + +Logic Block +----------- + +Each logic tile has a logic block containing 8 logic cells. Each logic +cell contains a 4-input LUT, a carry unit and a flip-flop. Clock, clock +enable, and set/reset inputs are shared along the 8 logic cells. So is +the bit that configures positive/negative edge for the flip flops. But +the three configuration bits that specify if the flip flop should be +used, if it is set or reset by the set/reset input, and if the set/reset +is synchronous or asynchronous exist for each logic cell individually. + +Each LUT *i* has four input wires lutff\_\ i/in_0 to lutff\_\ i/in_3. +Input lutff\_\ i/in_3 can be configured to be driven by the carry output +of the previous logic cell, or by carry_in_mux in case of *i*\ =0. Input +lutff\_\ i/in_2 can be configured to be driven by the output of the +previous LUT for *i*>0 (LUT cascade). The LUT uses its 4 input signals +to calculate lutff\_\ i/lout. The signal is then passed through the +built-in FF and becomes lutff\_\ i/out. With the exception of LUT +cascades, only the signal after the FF is visible from outside the logic +block. + +The carry unit calculates lutff\_\ i/cout = lutff\_\ i/in_1 + +lutff\_\ i/in_2 + lutff\_\ (i-1)/cout > 1. In case of *i*\ =0, +carry_in_mux is used as third input. carry_in_mux can be configured to +be constant 0, 1 or the lutff_7/cout signal from the logic tile below. + +Part of the functionality described above is documented as part of the +routing bitstream documentation (see the buffers for lutff\_ inputs). +The NegClk bit switches all 8 FFs in the tile to negative edge mode. The +CarryInSet bit drives the carry_in_mux high (it defaults to low when not +driven via the buffer from carry_in). + +The remaining functions of the logic cell are configured via the LC\_\ i +bits. This are 20 bit per logic cell. We have arbitrarily labeled those +bits as follows: + ++-----------------+--------+--------+--------+--------+--------+---------+---------+---------+ +| Label | LC_0 | LC_1 | LC_2 | LC_3 | LC_4 | LC_5 | LC_6 | LC_7 | ++=================+========+========+========+========+========+=========+=========+=========+ +| LC\_\ *i*\ [0] | B0[36] | B2[36] | B4[36] | B6[36] | B8[36] | B10[36] | B12[36] | B14[36] | ++-----------------+--------+--------+--------+--------+--------+---------+---------+---------+ +| LC\_\ *i*\ [1] | B0[37] | B2[37] | B4[37] | B6[37] | B8[37] | B10[37] | B12[37] | B14[37] | ++-----------------+--------+--------+--------+--------+--------+---------+---------+---------+ +| LC\_\ *i*\ [2] | B0[38] | B2[38] | B4[38] | B6[38] | B8[38] | B10[38] | B12[38] | B14[38] | ++-----------------+--------+--------+--------+--------+--------+---------+---------+---------+ +| LC\_\ *i*\ [3] | B0[39] | B2[39] | B4[39] | B6[39] | B8[39] | B10[39] | B12[39] | B14[39] | ++-----------------+--------+--------+--------+--------+--------+---------+---------+---------+ +| LC\_\ *i*\ [4] | B0[40] | B2[40] | B4[40] | B6[40] | B8[40] | B10[40] | B12[40] | B14[40] | ++-----------------+--------+--------+--------+--------+--------+---------+---------+---------+ +| LC\_\ *i*\ [5] | B0[41] | B2[41] | B4[41] | B6[41] | B8[41] | B10[41] | B12[41] | B14[41] | ++-----------------+--------+--------+--------+--------+--------+---------+---------+---------+ +| LC\_\ *i*\ [6] | B0[42] | B2[42] | B4[42] | B6[42] | B8[42] | B10[42] | B12[42] | B14[42] | ++-----------------+--------+--------+--------+--------+--------+---------+---------+---------+ +| LC\_\ *i*\ [7] | B0[43] | B2[43] | B4[43] | B6[43] | B8[43] | B10[43] | B12[43] | B14[43] | ++-----------------+--------+--------+--------+--------+--------+---------+---------+---------+ +| LC\_\ *i*\ [8] | B0[44] | B2[44] | B4[44] | B6[44] | B8[44] | B10[44] | B12[44] | B14[44] | ++-----------------+--------+--------+--------+--------+--------+---------+---------+---------+ +| LC\_\ *i*\ [9] | B0[45] | B2[45] | B4[45] | B6[45] | B8[45] | B10[45] | B12[45] | B14[45] | ++-----------------+--------+--------+--------+--------+--------+---------+---------+---------+ +| LC\_\ *i*\ [10] | B1[36] | B3[36] | B5[36] | B7[36] | B9[36] | B11[36] | B13[36] | B15[36] | ++-----------------+--------+--------+--------+--------+--------+---------+---------+---------+ +| LC\_\ *i*\ [11] | B1[37] | B3[37] | B5[37] | B7[37] | B9[37] | B11[37] | B13[37] | B15[37] | ++-----------------+--------+--------+--------+--------+--------+---------+---------+---------+ +| LC\_\ *i*\ [12] | B1[38] | B3[38] | B5[38] | B7[38] | B9[38] | B11[38] | B13[38] | B15[38] | ++-----------------+--------+--------+--------+--------+--------+---------+---------+---------+ +| LC\_\ *i*\ [13] | B1[39] | B3[39] | B5[39] | B7[39] | B9[39] | B11[39] | B13[39] | B15[39] | ++-----------------+--------+--------+--------+--------+--------+---------+---------+---------+ +| LC\_\ *i*\ [14] | B1[40] | B3[40] | B5[40] | B7[40] | B9[40] | B11[40] | B13[40] | B15[40] | ++-----------------+--------+--------+--------+--------+--------+---------+---------+---------+ +| LC\_\ *i*\ [15] | B1[41] | B3[41] | B5[41] | B7[41] | B9[41] | B11[41] | B13[41] | B15[41] | ++-----------------+--------+--------+--------+--------+--------+---------+---------+---------+ +| LC\_\ *i*\ [16] | B1[42] | B3[42] | B5[42] | B7[42] | B9[42] | B11[42] | B13[42] | B15[42] | ++-----------------+--------+--------+--------+--------+--------+---------+---------+---------+ +| LC\_\ *i*\ [17] | B1[43] | B3[43] | B5[43] | B7[43] | B9[43] | B11[43] | B13[43] | B15[43] | ++-----------------+--------+--------+--------+--------+--------+---------+---------+---------+ +| LC\_\ *i*\ [18] | B1[44] | B3[44] | B5[44] | B7[44] | B9[44] | B11[44] | B13[44] | B15[44] | ++-----------------+--------+--------+--------+--------+--------+---------+---------+---------+ +| LC\_\ *i*\ [19] | B1[45] | B3[45] | B5[45] | B7[45] | B9[45] | B11[45] | B13[45] | B15[45] | ++-----------------+--------+--------+--------+--------+--------+---------+---------+---------+ + +LC\_\ i\ [8] is the CarryEnable bit. This bit must be set if the carry +logic is used. + +LC\_\ i\ [9] is the DffEnable bit. It enables the output flip-flop for +the LUT. + +LC\_\ i\ [18] is the Set_NoReset bit. When this bit is set then the +set/reset signal will set, not reset the flip-flop. + +LC\_\ i\ [19] is the AsyncSetReset bit. When this bit is set then the +set/reset signal is asynchronous to the clock. + +The LUT implements the following truth table: + +==== ==== ==== ==== ============= +in_3 in_2 in_1 in_0 lout +==== ==== ==== ==== ============= +0 0 0 0 LC\_\ i\ [4] +0 0 0 1 LC\_\ i\ [14] +0 0 1 0 LC\_\ i\ [15] +0 0 1 1 LC\_\ i\ [5] +0 1 0 0 LC\_\ i\ [6] +0 1 0 1 LC\_\ i\ [16] +0 1 1 0 LC\_\ i\ [17] +0 1 1 1 LC\_\ i\ [7] +1 0 0 0 LC\_\ i\ [3] +1 0 0 1 LC\_\ i\ [13] +1 0 1 0 LC\_\ i\ [12] +1 0 1 1 LC\_\ i\ [2] +1 1 0 0 LC\_\ i\ [1] +1 1 0 1 LC\_\ i\ [11] +1 1 1 0 LC\_\ i\ [10] +1 1 1 1 LC\_\ i\ [0] +==== ==== ==== ==== ============= + +LUT inputs that are not connected to anything are driven low. The +set/reset signal is also driven low if not connected to any other +driver, and the clock enable signal is driven high when left +unconnected. + +.. |Span-4 Horizontal| image:: _static/images/sp4h.svg + :height: 200px + :target: sp4h.svg +.. |Span-4 Vertical| image:: _static/images/sp4v.svg + :height: 200px + :target: sp4v.svg diff --git a/docs/source/notes_osx.rst b/docs/source/notes_osx.rst new file mode 100644 index 0000000..dbc2f33 --- /dev/null +++ b/docs/source/notes_osx.rst @@ -0,0 +1,72 @@ +Notes for Installing on OSX +=========================== + +The toolchain should be easy to install on OSX platforms. Below are a +few troubleshooting items found on Mountain Lion (10.8.2). + +See https://github.com/ddm/icetools for a set of shell scripts to build +IceStorm on OSX (using brew for dependencies). + +Installing FTDI Library +----------------------- + +The libftdi package (.so lib binary and the ftdi.h header) has been +renamed to libftdi0, so either do: + +| ``port install libftdi0`` +| (note that ports installs the tool to /opt instead of /usr, see + next note) + +``brew install libftdi0`` + +iceprog make error on "ftdi.h not found" +---------------------------------------- + +Note that Mac Ports installs to /opt instead of /usr, so change the +first two lines in ``iceprog/Makefile`` to: + +:: + + LDLIBS = -L/usr/local/lib -L/opt/local/lib -lftdi -lm + CFLAGS = -MD -O0 -ggdb -Wall -std=c99 -I/usr/local/include -I/opt/local/include/ + +Basically you are indicating where to find the lib with +``-L/opt/local/lib`` and where to find the .h with +``-I/opt/local/include/``. + +yosys make error on " not found" +--------------------------------------- + +This is a compiler issue, i.e., you are probably running on clang and +you can circumvent this error by compiling against another compiler. +Edit the Makefile of yosys and replace the two first lines for this, +i.e., comment the first line (clang) and uncomment the second (gcc): + +:: + + #CONFIG := clang + CONFIG := gcc + +error "Can't find iCE FTDI USB device (vendor_id 0x0403, device_id 0x6010)." while uploading code to FPGA (e.g., "iceprog example.bin") +--------------------------------------------------------------------------------------------------------------------------------------- + +You need to unload the FTDI driver (notes below are from Mountain Lion, +10.8.2). First check if it is running: + +:: + + kextstat | grep FTDIUSBSerialDriver + +If you see it on the kextstat, we need to unload it: + +:: + + sudo kextunload -b com.FTDI.driver.FTDIUSBSerialDriver + +Repeat the ``kextstat`` command and check that the driver was +successfully unloaded. + +Try running ``iceprog example.bin`` again. It should be working now. + +Note: On newer OSes perhaps you need to also kextunload the +``com.apple.driver.AppleUSBFTDI`` driver. diff --git a/docs/source/overview.rst b/docs/source/overview.rst new file mode 100644 index 0000000..40dab79 --- /dev/null +++ b/docs/source/overview.rst @@ -0,0 +1,740 @@ +Project IceStorm +================ + +| **2018-01-30:** Released support for iCE40 UltraPlus devices. +| **2017-03-13:** Released support for LP384 chips (in all package + variants). +| **2016-02-07:** Support for all package variants of LP1K, LP4K, LP8K + and HX1K, HX4K, and HX8K. +| **2016-01-17:** First release of IceTime timing analysis. Video: + https://youtu.be/IG5CpFJRnOk +| **2015-12-27:** + `Presentation `__ + of the IceStorm flow at 32C3 (`Video on + Youtube `__). +| **2015-07-19:** Released support for 8k chips. Moved IceStorm source + code to GitHub. +| **2015-05-27:** We have a working fully Open Source flow with + `Yosys `__ and + `Arachne-pnr `__! Video: + http://youtu.be/yUiNlmvVOq8 +| **2015-04-13:** Complete rewrite of IceUnpack, added IcePack, some + major documentation updates +| **2015-03-22:** First public release and short YouTube video + demonstrating our work: http://youtu.be/u1ZHcSNDQMM + +What is Project IceStorm? +------------------------- + +Project IceStorm aims at documenting the bitstream format of Lattice +iCE40 FPGAs and providing simple tools for analyzing and creating +bitstream files. The IceStorm flow +(`Yosys `__, +`Arachne-pnr `__, and IceStorm) is +a fully open source Verilog-to-Bitstream flow for iCE40 FPGAs. + +The focus of the project is on the iCE40 LP/HX 1K/4K/8K chips. (Most of +the work was done on HX1K-TQ144 and HX8K-CT256 parts.) The iCE40 +UltraPlus parts are also supported, including DSPs, oscillators, RGB and +SPRAM. iCE40 LM, Ultra and UltraLite parts are not yet supported. + +Why the Lattice iCE40? +---------------------- + +It has a very minimalistic architecture with a very regular structure. +There are not many different kinds of tiles or special function units. +This makes it both ideal for creating bitstream documentations and as a +reference platform for general purpose FPGA tool development. + +Also, with the `Lattice +iCEstick `__ there is a cheap and +easy to use development platform available, which makes the part +interesting for all kinds of projects. (The iCEstick features an HX1K +device. Lattice also sells an `iCE40-HX8K Breakout +Board `__ +featuring an HX8K chip.) + +What is the Status of the Project? +---------------------------------- + +We are pretty confident that we have the 1K and 8K devices completely +documented. For example, it seems we can create correct functional +Verilog models for all bitstreams generated by Lattice iCEcube2 for the +iCE40 HX1K-TQ144 and the iCE40 HX8K-CT256 using our ``icebox_vlog`` +tool. + +Here is a list of currently supported parts and the corresponding +options for arachne-pnr (place and route) and icetime (timing analysis): + ++---------+---------+---------+------+---------+---------+---------+ +| Part | Package | Pin | I/Os | nextpnr | arac | icetime | +| | | Spacing | | opts | hne-pnr | opts | +| | | | | | opts | | ++=========+=========+=========+======+=========+=========+=========+ +| iCE4 | 16-ball | 0.35 mm | 10 | --lp1k | -d 1k | -d lp1k | +| 0-LP1K- | WLCSP | | | -- | -P | | +| SWG16TR | (1.40 x | | | package | swg16tr | | +| | 1.48 | | | swg16tr | | | +| | mm) | | | | | | ++---------+---------+---------+------+---------+---------+---------+ +| iC | 30-ball | 0.40 mm | 21 | --up5k | -d 5k | -d up5k | +| E40-UP3 | WLCSP | | | -- | -P | | +| K-UWG30 | (2.15 x | | | package | uwg30 | | +| | 2.55 | | | uwg30 | | | +| | mm) | | | | | | ++---------+---------+---------+------+---------+---------+---------+ +| iC | 30-ball | 0.40 mm | 21 | --up5k | -d 5k | -d up5k | +| E40-UP5 | WLCSP | | | -- | -P | | +| K-UWG30 | (2.15 x | | | package | uwg30 | | +| | 2.55 | | | uwg30 | | | +| | mm) | | | | | | ++---------+---------+---------+------+---------+---------+---------+ +| iC | 36-ball | 0.40 mm | 25 | --lp384 | -d 384 | -d | +| E40-LP3 | ucBGA | | | -- | -P cm36 | lp384 | +| 84-CM36 | (2.5 x | | | package | | | +| | 2.5 mm) | | | cm36 | | | ++---------+---------+---------+------+---------+---------+---------+ +| i | 36-ball | 0.40 mm | 25 | --lp1k | -d 1k | -d lp1k | +| CE40-LP | ucBGA | | | -- | -P cm36 | | +| 1K-CM36 | (2.5 x | | | package | | | +| | 2.5 mm) | | | cm36 | | | ++---------+---------+---------+------+---------+---------+---------+ +| iC | 49-ball | 0.40 mm | 37 | --lp384 | -d 384 | -d | +| E40-LP3 | ucBGA | | | -- | -P cm49 | lp384 | +| 84-CM49 | (3 x 3 | | | package | | | +| | mm) | | | cm49 | | | ++---------+---------+---------+------+---------+---------+---------+ +| i | 49-ball | 0.40 mm | 35 | --lp1k | -d 1k | -d lp1k | +| CE40-LP | ucBGA | | | -- | -P cm49 | | +| 1K-CM49 | (3 x 3 | | | package | | | +| | mm) | | | cm49 | | | ++---------+---------+---------+------+---------+---------+---------+ +| i | 81-ball | 0.40 mm | 63 | --lp1k | -d 1k | -d lp1k | +| CE40-LP | ucBGA | | | -- | -P cm81 | | +| 1K-CM81 | (4 x 4 | | | package | | | +| | mm) | | | cm81 | | | ++---------+---------+---------+------+---------+---------+---------+ +| i | 81-ball | 0.40 mm | 63 | --lp8k | -d 8k | -d lp8k | +| CE40-LP | ucBGA | | | -- | -P | | +| 4K-CM81 | (4 x 4 | | | package | cm81:4k | | +| | mm) | | | cm81:4k | | | ++---------+---------+---------+------+---------+---------+---------+ +| i | 81-ball | 0.40 mm | 63 | --lp9k | -d 8k | -d lp8k | +| CE40-LP | ucBGA | | | -- | -P cm81 | | +| 8K-CM81 | (4 x 4 | | | package | | | +| | mm) | | | cm81 | | | ++---------+---------+---------+------+---------+---------+---------+ +| iC | 1 | 0.40 mm | 95 | --lp1k | -d 1k | -d lp1k | +| E40-LP1 | 21-ball | | | -- | -P | | +| K-CM121 | ucBGA | | | package | cm121 | | +| | (5 x 5 | | | cm121 | | | +| | mm) | | | | | | ++---------+---------+---------+------+---------+---------+---------+ +| iC | 1 | 0.40 mm | 93 | --lp8k | -d 8k | -d lp8k | +| E40-LP4 | 21-ball | | | -- | -P | | +| K-CM121 | ucBGA | | | package | c | | +| | (5 x 5 | | | c | m121:4k | | +| | mm) | | | m121:4k | | | ++---------+---------+---------+------+---------+---------+---------+ +| iC | 1 | 0.40 mm | 93 | --lp8k | -d 8k | -d lp8k | +| E40-LP8 | 21-ball | | | -- | -P | | +| K-CM121 | ucBGA | | | package | cm121 | | +| | (5 x 5 | | | cm121 | | | +| | mm) | | | | | | ++---------+---------+---------+------+---------+---------+---------+ +| iC | 2 | 0.40 mm | 167 | --lp8k | -d 8k | -d lp8k | +| E40-LP4 | 25-ball | | | -- | -P | | +| K-CM225 | ucBGA | | | package | c | | +| | (7 x 7 | | | c | m225:4k | | +| | mm) | | | m225:4k | | | ++---------+---------+---------+------+---------+---------+---------+ +| iC | 2 | 0.40 mm | 178 | --lp8k | -d 8k | -d lp8k | +| E40-LP8 | 25-ball | | | -- | -P | | +| K-CM225 | ucBGA | | | package | cm225 | | +| | (7 x 7 | | | cm225 | | | +| | mm) | | | | | | ++---------+---------+---------+------+---------+---------+---------+ +| iC | 2 | 0.40 mm | 178 | --hx8k | -d 8k | -d hx8k | +| E40-HX8 | 25-ball | | | -- | -P | | +| K-CM225 | ucBGA | | | package | cm225 | | +| | (7 x 7 | | | cm225 | | | +| | mm) | | | | | | ++---------+---------+---------+------+---------+---------+---------+ +| iC | 32-pin | 0.50 mm | 21 | --lp384 | -d 384 | -d | +| E40-LP3 | QFN (5 | | | -- | -P qn32 | lp384 | +| 84-QN32 | x 5 mm) | | | package | | | +| | | | | qn32 | | | ++---------+---------+---------+------+---------+---------+---------+ +| i | 48-pin | 0.50 mm | 39 | --up5k | -d 5k | -d up5k | +| CE40-UP | QFN (7 | | | -- | -P sg48 | | +| 5K-SG48 | x 7 mm) | | | package | | | +| | | | | sg48 | | | ++---------+---------+---------+------+---------+---------+---------+ +| i | 84-pin | 0.50 mm | 67 | --lp1k | -d 1k | -d lp1k | +| CE40-LP | QFNS (7 | | | -- | -P qn84 | | +| 1K-QN84 | x 7 mm) | | | package | | | +| | | | | qn84 | | | ++---------+---------+---------+------+---------+---------+---------+ +| i | 81-ball | 0.50 mm | 62 | --lp1k | -d 1k | -d lp1k | +| CE40-LP | csBGA | | | -- | -P cb81 | | +| 1K-CB81 | (5 x 5 | | | package | | | +| | mm) | | | cb81 | | | ++---------+---------+---------+------+---------+---------+---------+ +| iC | 1 | 0.50 mm | 92 | --lp1k | -d 1k | -d lp1k | +| E40-LP1 | 21-ball | | | -- | -P | | +| K-CB121 | csBGA | | | package | cb121 | | +| | (6 x 6 | | | cb121 | | | +| | mm) | | | | | | ++---------+---------+---------+------+---------+---------+---------+ +| iC | 1 | 0.50 mm | 95 | --hx1k | -d 1k | -d hx1k | +| E40-HX1 | 32-ball | | | -- | -P | | +| K-CB132 | csBGA | | | package | cb132 | | +| | (8 x 8 | | | cb132 | | | +| | mm) | | | | | | ++---------+---------+---------+------+---------+---------+---------+ +| iC | 1 | 0.50 mm | 95 | --hx8k | -d 8k | -d hx8k | +| E40-HX4 | 32-ball | | | -- | -P | | +| K-CB132 | csBGA | | | package | c | | +| | (8 x 8 | | | c | b132:4k | | +| | mm) | | | b132:4k | | | ++---------+---------+---------+------+---------+---------+---------+ +| iC | 1 | 0.50 mm | 95 | --hx8k | -d 8k | -d hx8k | +| E40-HX8 | 32-ball | | | -- | -P | | +| K-CB132 | csBGA | | | package | cb132 | | +| | (8 x 8 | | | cb132 | | | +| | mm) | | | | | | ++---------+---------+---------+------+---------+---------+---------+ +| iC | 100-pin | 0.50 mm | 72 | --hx1k | -d 1k | -d hx1k | +| E40-HX1 | VQFP | | | -- | -P | | +| K-VQ100 | (14 x | | | package | vq100 | | +| | 14 mm) | | | vq100 | | | ++---------+---------+---------+------+---------+---------+---------+ +| iC | 144-pin | 0.50 mm | 96 | --hx1k | -d 1k | -d hx1k | +| E40-HX1 | TQFP | | | -- | -P | | +| K-TQ144 | (20 x | | | package | tq144 | | +| | 20 mm) | | | tq144 | | | ++---------+---------+---------+------+---------+---------+---------+ +| iC | 144-pin | 0.50 mm | 107 | --hx8k | -d 8k | -d hx8k | +| E40-HX4 | TQFP | | | -- | -P | | +| K-TQ144 | (20 x | | | package | t | | +| | 20 mm) | | | t | q144:4k | | +| | | | | q144:4k | | | ++---------+---------+---------+------+---------+---------+---------+ +| iC | 1 | 0.80 mm | 93 | --hx8k | -d 8k | -d hx8k | +| E40-HX4 | 21-ball | | | -- | -P | | +| K-BG121 | caBGA | | | package | b | | +| | (9 x 9 | | | b | g121:4k | | +| | mm) | | | g121:4k | | | ++---------+---------+---------+------+---------+---------+---------+ +| iC | 1 | 0.80 mm | 93 | --hx8k | -d 8k | -d hx8k | +| E40-HX8 | 21-ball | | | -- | -P | | +| K-BG121 | caBGA | | | package | bg121 | | +| | (9 x 9 | | | bg121 | | | +| | mm) | | | | | | ++---------+---------+---------+------+---------+---------+---------+ +| iC | 2 | 0.80 mm | 206 | --hx8k | -d 8k | -d hx8k | +| E40-HX8 | 56-ball | | | -- | -P | | +| K-CT256 | caBGA | | | package | ct256 | | +| | (14 x | | | ct256 | | | +| | 14 mm) | | | | | | ++---------+---------+---------+------+---------+---------+---------+ + +Current work focuses on further improving our timing analysis flow. + +How do I use the Fully Open Source iCE40 Flow? +---------------------------------------------- + +Synthesis for iCE40 FPGAs can be done with +`Yosys `__. Place-and-route can be +done with `arachne-pnr `__. Here +is an example script for implementing and programming the `rot example +from +arachne-pnr `__ +(this example targets the iCEstick development board): + +:: + + yosys -p "synth_ice40 -blif rot.blif" rot.v + arachne-pnr -d 1k -p rot.pcf rot.blif -o rot.asc + icepack rot.asc rot.bin + iceprog rot.bin + +A simple timing analysis report can be generated using the ``icetime`` +utility: + +:: + + icetime -tmd hx1k rot.asc + +.. _install: + +Where are the Tools? How to install? +------------------------------------ + +Installing prerequisites (this command is for Ubuntu 14.04): + +:: + + sudo apt-get install build-essential clang bison flex libreadline-dev \ + gawk tcl-dev libffi-dev git mercurial graphviz \ + xdot pkg-config python python3 libftdi-dev \ + qt5-default python3-dev libboost-all-dev cmake libeigen3-dev + +On Fedora 24 the following command installs all prerequisites: + +:: + + sudo dnf install make automake gcc gcc-c++ kernel-devel clang bison \ + flex readline-devel gawk tcl-devel libffi-devel git mercurial \ + graphviz python-xdot pkgconfig python python3 libftdi-devel \ + qt5-devel python3-devel boost-devel boost-python3-devel eigen3-devel + +Note: All tools will be installed relative to /usr/local + +Installing the `IceStorm Tools `__ +(icepack, icebox, iceprog, icetime, chip databases): + +:: + + git clone https://github.com/YosysHQ/icestorm.git icestorm + cd icestorm + make -j$(nproc) + sudo make install + +Installing `Arachne-PNR `__ +(place&route tool, predecessor to NextPNR): + +:: + + git clone https://github.com/cseed/arachne-pnr.git arachne-pnr + cd arachne-pnr + make -j$(nproc) + sudo make install + +Installing `NextPNR `__ (place&route +tool, Arachne-PNR replacement): + +:: + + git clone --recursive https://github.com/YosysHQ/nextpnr nextpnr + cd nextpnr + cmake -DARCH=ice40 -DCMAKE_INSTALL_PREFIX=/usr/local . + make -j$(nproc) + sudo make install + +Installing `Yosys `__ (Verilog +synthesis): + +:: + + git clone https://github.com/YosysHQ/yosys.git yosys + cd yosys + make -j$(nproc) + sudo make install + +Both place and route tools (Arachne-PNR & NextPNR) convert the IceStorm +text chip databases into the respective PNR binary chip databases during +build. Always rebuild the PNR tools after updating your IceStorm +installation. + +**Notes for Linux:** Create a file +``/etc/udev/rules.d/53-lattice-ftdi.rules`` with the following line in +it to allow uploading bit-streams to a Lattice iCEstick and/or a Lattice +iCE40-HX8K Breakout Board as unprivileged user: + +:: + + ATTRS{idVendor}=="0403", ATTRS{idProduct}=="6010", MODE="0660", GROUP="plugdev", TAG+="uaccess" + +**Notes for Archlinux:** just install +`icestorm-git `__, +`arachne-pnr-git `__ +and `yosys-git `__ from +the Arch User Repository (no need to follow the install instructions +above). + +**Notes for OSX:** Please follow the `additional instructions for +OSX `__ to install on OSX. + +Please `file an issue on +github `__ if you have +additional notes to share regarding the install procedures on the +operating system of your choice. + +What are the IceStorm Tools? +---------------------------- + +The IceStorm Tools are a couple of small programs for working with iCE40 +bitstream files and our ASCII representation of it. The complete Open +Source iCE40 Flow consists of the `IceStorm +Tools `__, +`Arachne-PNR `__, and +`Yosys `__. + +IcePack/IceUnpack +~~~~~~~~~~~~~~~~~ + +The iceunpack program converts an iCE40 .bin file into the IceStorm +ASCII format that has blocks of 0 and 1 for the config bits for each +tile in the chip. The icepack program converts such an ASCII file back +to an iCE40 .bin file. All other IceStorm Tools operate on the ASCII +file format, not the bitstream binaries. + +IceTime +~~~~~~~ + +The icetime program is an iCE40 timing analysis tool. It reads designs +in IceStorm ASCII format and writes times timing netlists that can be +used in external timing analysers. It also includes a simple topological +timing analyser that can be used to create timing reports. + +IceBox +~~~~~~ + +A python library and various tools for working with IceStorm ASCII files +and accessing the device database. For example icebox_vlog converts our +ASCII file dump of a bitstream into a Verilog file that implements an +equivalent circuit. + +IceProg +~~~~~~~ + +A small driver program for the FTDI-based programmer used on the +iCEstick and HX8K development boards. + +IceMulti +~~~~~~~~ + +A tool for packing multiple bitstream files into one iCE40 multiboot +image file. + +IcePLL +~~~~~~ + +A small program for calculating iCE40 PLL configuration parameters. + +IceBRAM +~~~~~~~ + +A small program for swapping the BRAM contents in IceStorm ASCII files. +E.g. for changing the firmware image in a SoC design without re-running +synthesis and place&route. + +ChipDB +~~~~~~ + +The IceStorm Makefile builds and installs two files: chipdb-1k.txt and +chipdb-8k.txt. This files contain all the relevant information for +arachne-pnr to place&route a design and create an IceStorm ASCII file +for the placed and routed design. + +*IcePack/IceUnpack, IceBox, IceProg, IceTime, and IcePLL are written by +Claire Wolf. IcePack/IceUnpack is based on a reference implementation +provided by Mathias Lasser. IceMulti is written by Marcus Comstedt.* + +Where do I get support or meet other IceStorm users? +---------------------------------------------------- + +If you have a question regarding the IceStorm flow, use the `yosys tag +on stackoverflow `__ to +ask your question. If your question is a general question about Verilog +HDL design, please consider using the `verilog tag on +stackoverflow `__ +instead. + +For general discussions go to the `Yosys +Subreddit `__ or `#yosys on freenode +IRC `__. + +If you have a bug report please file an issue on github. (`IceStorm +Issue Tracker `__, `Yosys +Issue Tracker `__, `Arachne-PNR +Issue Tracker `__) + +.. _docs: + +Where is the Documentation? +--------------------------- + +Recommended reading: `Lattice iCE40 LP/HX Family +Datasheet `__, +`Lattice iCE Technology +Library `__ +(Especially the three pages on "Architecture Overview", "PLB Blocks", +"Routing", and "Clock/Control Distribution Network" in the Lattice iCE40 +LP/HX Family Datasheet. Read that first, then come back here.) + +The FPGA fabric is divided into tiles. There are IO, RAM and LOGIC +tiles. + +- `LOGIC Tile Documentation `__ +- `IO Tile Documentation `__ +- `RAM Tile Documentation `__ +- `The Bitstream File Format `__ +- `The iCE40 HX1K Bit Docs `__ +- `The iCE40 HX8K Bit Docs `__ +- `Notes on UltraPlus features `__ + +The iceunpack program can be used to convert the bitstream into an ASCII +file that has a block of 0 and 1 characters for each tile. For example: + +:: + + .logic_tile 12 12 + 000000000000000000000000000000000000000000000000000000 + 000000000000000000000011010000000000000000000000000000 + 000000000000000000000000000000000000000000000000000000 + 000000000000000000000000000000000000000000000000000000 + 000000000000000000000000000000000000000000000000000000 + 000000000000000000000000000000000000000000000000000000 + 000000000000000000000000000000000000000000000000000000 + 000000000000001011000000000000000000000000000000000000 + 000000000000000000000000000000000000000000000000000000 + 000000000000000000000000000000000000000000000000000000 + 000000000000000000000000000000000000000000000000000000 + 000000000000000000000000000000000000000000000000000000 + 000000000000000000000000000000000000000000000000000000 + 000000000000000000000000000000000000000000000000000000 + 000000000000000000000000001000001000010101010000000000 + 000000000000000000000000000101010000101010100000000000 + +This bits are referred to as B\ y\ [x] in the documentation. For +example, B0 is the first line, B0[0] the first bit in the first line, +and B15[53] the last bit in the last line. + +The icebox_explain program can be used to turn this block of config bits +into a description of the cell configuration: + +:: + + .logic_tile 12 12 + LC_7 0101010110101010 0000 + buffer local_g0_2 lutff_7/in_3 + buffer local_g1_4 lutff_7/in_0 + buffer sp12_h_r_18 local_g0_2 + buffer sp12_h_r_20 local_g1_4 + +IceBox contains a database of the wires and configuration bits that can +be found in iCE40 tiles. This database can be accessed via the IceBox +Python API. But IceBox is a large hack. So it is recommended to only use +the IceBox API to export this database into a format that fits the +target application. See icebox_chipdb for an example program that does +that. + +The recommended approach for learning how to use this documentation is +to synthesize very simple circuits using Yosys and Arachne-pnr, run the +icestorm tool icebox_explain on the resulting bitstream files, and +analyze the results using the HTML export of the database mentioned +above. icebox_vlog can be used to convert the bitstream to Verilog. The +output file of this tool will also outline the signal paths in comments +added to the generated Verilog code. + +For example, consider the following Verilog and PCF files: + +:: + + // example.v + module top (input a, b, output y); + assign y = a & b; + endmodule + + # example.pcf + set_io a 1 + set_io b 10 + set_io y 11 + +And run them through Yosys, Arachne-PNR and IcePack: + +:: + + $ yosys -p 'synth_ice40 -top top -blif example.blif' example.v + $ arachne-pnr -d 1k -o example.asc -p example.pcf example.blif + $ icepack example.asc example.bin + +We would get something like the following icebox_explain output: + +:: + + $ icebox_explain example.asc + Reading file 'example.asc'.. + Fabric size (without IO tiles): 12 x 16 + + .io_tile 0 10 + IOB_1 PINTYPE_0 + IOB_1 PINTYPE_3 + IOB_1 PINTYPE_4 + IoCtrl IE_0 + IoCtrl IE_1 + IoCtrl REN_0 + buffer local_g0_5 io_1/D_OUT_0 + buffer logic_op_tnr_5 local_g0_5 + + .io_tile 0 14 + IOB_1 PINTYPE_0 + IoCtrl IE_1 + IoCtrl REN_0 + buffer io_1/D_IN_0 span4_vert_b_6 + + .io_tile 0 11 + IOB_0 PINTYPE_0 + IoCtrl IE_0 + IoCtrl REN_1 + routing span4_vert_t_14 span4_horz_13 + + .logic_tile 1 11 + LC_5 0001000000000000 0000 + buffer local_g0_0 lutff_5/in_1 + buffer local_g3_0 lutff_5/in_0 + buffer neigh_op_lft_0 local_g0_0 + buffer sp4_h_r_24 local_g3_0 + +And something like the following icebox_vlog output: + +:: + + $ icebox_vlog -p example.pcf example.asc + // Reading file 'example.asc'.. + + module chip (output y, input b, input a); + + wire y; + // io_0_10_1 + // (0, 10, 'io_1/D_OUT_0') + // (0, 10, 'io_1/PAD') + // (0, 10, 'local_g0_5') + // (0, 10, 'logic_op_tnr_5') + // (0, 11, 'logic_op_rgt_5') + // (0, 12, 'logic_op_bnr_5') + // (1, 10, 'neigh_op_top_5') + // (1, 11, 'lutff_5/out') + // (1, 12, 'neigh_op_bot_5') + // (2, 10, 'neigh_op_tnl_5') + // (2, 11, 'neigh_op_lft_5') + // (2, 12, 'neigh_op_bnl_5') + + wire b; + // io_0_11_0 + // (0, 11, 'io_0/D_IN_0') + // (0, 11, 'io_0/PAD') + // (1, 10, 'neigh_op_tnl_0') + // (1, 10, 'neigh_op_tnl_4') + // (1, 11, 'local_g0_0') + // (1, 11, 'lutff_5/in_1') + // (1, 11, 'neigh_op_lft_0') + // (1, 11, 'neigh_op_lft_4') + // (1, 12, 'neigh_op_bnl_0') + // (1, 12, 'neigh_op_bnl_4') + + wire a; + // io_0_14_1 + // (0, 11, 'span4_horz_13') + // (0, 11, 'span4_vert_t_14') + // (0, 12, 'span4_vert_b_14') + // (0, 13, 'span4_vert_b_10') + // (0, 14, 'io_1/D_IN_0') + // (0, 14, 'io_1/PAD') + // (0, 14, 'span4_vert_b_6') + // (0, 15, 'span4_vert_b_2') + // (1, 11, 'local_g3_0') + // (1, 11, 'lutff_5/in_0') + // (1, 11, 'sp4_h_r_24') + // (1, 13, 'neigh_op_tnl_2') + // (1, 13, 'neigh_op_tnl_6') + // (1, 14, 'neigh_op_lft_2') + // (1, 14, 'neigh_op_lft_6') + // (1, 15, 'neigh_op_bnl_2') + // (1, 15, 'neigh_op_bnl_6') + // (2, 11, 'sp4_h_r_37') + // (3, 11, 'sp4_h_l_37') + + assign y = /* LUT 1 11 5 */ b ? a : 0; + + endmodule + +Links +----- + +Links to related projects. Contact me at claire@clairexen.net if you +have an interesting and relevant link. + +- `J1a SwapForth built with + IceStorm `__ +- `Lattice iCEBlink40 Programming + Tool `__ +- `Another iCEBlink40 Programming + Tool `__ +- `iCE40 layout viewer `__ +- `icedrom iCE40 netlist viewer `__ + +iCE40 Boards +~~~~~~~~~~~~ + +- `Lattice iCEstick `__ +- `Lattice iCE40-HX8K Breakout + Board `__ +- `IcoBoard `__ +- `wiggleport `__ +- `ICEd = an Arduino Style Board, with ICE + FPGA `__ +- `CAT Board `__ +- `eCow-Logic pico-ITX Lattice ICE40 + board `__ +- `Nandland Go + Board `__ +- `myStorm board (iCE40 + + STM32) `__ +- `DSP iCE board (another iCE40 + STM32 + board) `__ +- `BeagleWire iCE40 FPGA BeagleBone + cape `__ + +Lectures and Tutorials +~~~~~~~~~~~~~~~~~~~~~~ + +- `A Free and Open Source Verilog-to-Bitstream Flow for iCE40 FPGAs + [32c3] `__ +- `Synthesizing Verilog for Lattice ICE40 FPGAs (Paul + Martin) `__ +- `A Spanish FPGA Tutorial using + IceStorm `__ +- `IceStorm Learner’s + Documentation `__ + +Other FPGA bitstream documentation projects +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +- `ECP5 bitstream documentation (Project + Trellis) `__ +- `Xilinx 7-series bitstream documentation (Project + X-Ray) `__ +- `Xilinx xc6slx9 documentation, Wolfgang + Spraul `__ +- `From the bitstream to the netlist, Jean-Baptiste Note and Éric + Rannaud `__ +- `Cyclone IV EP4CE6 documentation, Marek + Vasut `__ + +-------------- + +In papers and reports, please refer to Project IceStorm as follows: +Claire Wolf, Mathias Lasser. Project IceStorm. +http://bygone.clairexen.net/icestorm/, e.g. using the following BibTeX +code: + +:: + + @MISC{IceStorm, + author = {Claire Wolf and Mathias Lasser}, + title = {Project IceStorm}, + howpublished = "\url{http://bygone.clairexen.net/icestorm/}" + } + +-------------- + +*Documentation mostly by Claire Wolf in 2015. +Based on research by Mathias Lasser and Claire Wolf. +Buy an* `iCEstick `__ *or* +`iCE40-HX8K Breakout +Board `__ +*from Lattice and see what you can do with the tools and information +provided here.* diff --git a/docs/source/ram_tile.rst b/docs/source/ram_tile.rst new file mode 100644 index 0000000..d7888df --- /dev/null +++ b/docs/source/ram_tile.rst @@ -0,0 +1,79 @@ +RAM Tile Documentation +====================== + +Span-4 and Span-12 Wires +------------------------ + +Regarding the Span-4 and Span-12 Wires a RAM tile behaves exactly like a +LOGIC tile. So for simple applications that do not need the block ram +resources, the RAM tiles can be handled like a LOGIC tiles without logic +cells in them. + +Block RAM Resources +------------------- + +A pair or RAM tiles (odd and even y-coordinates) provides an interface +to a block ram cell. Like with LOGIC tiles, signals entering the RAM +tile have to be routed over local tracks to the block ram inputs. Tiles +with odd y-coordinates are "bottom" RAM Tiles (RAMB Tiles), and tiles +with even y-coordinates are "top" RAM Tiles (RAMT Tiles). Each pair of +RAMB/RAMT tiles implements a SB_RAM40_4K cell. The cell ports are spread +out over the two tiles as follows: + +=========== =========== =========== +SB_RAM40_4K RAMB Tile RAMT Tile +=========== =========== =========== +RDATA[15:0] RDATA[7:0] RDATA[15:8] +RADDR[10:0] -- RADDR[10:0] +WADDR[10:0] WADDR[10:0] -- +MASK[15:0] MASK[7:0] MASK[15:8] +WDATA[15:0] WDATA[7:0] WDATA[15:8] +RCLKE -- RCLKE +RCLK -- RCLK +RE -- RE +WCLKE WCLKE -- +WCLK WCLK -- +WE WE -- +=========== =========== =========== + +The configuration bit RamConfig PowerUp in the RAMB tile enables the +memory. This bit is active-low in 1k chips, i.e. an unused RAM block has +only this bit set. Note that icebox_explain.py will ignore all RAMB +tiles that only have the RamConfig PowerUp bit set. + +In 8k chips the RamConfig PowerUp bit is active-high. So an unused RAM +block has all bits cleared in the 8k config bitstream. + +The RamConfig CBIT\_\* bits in the RAMT tile configure the read/write +width of the memory. Those bits map to the SB_RAM40_4K cell parameters +as follows: + +============= ================ +SB_RAM40_4K RAMT Config Bit +============= ================ +WRITE_MODE[0] RamConfig CBIT_0 +WRITE_MODE[1] RamConfig CBIT_1 +READ_MODE[0] RamConfig CBIT_2 +READ_MODE[1] RamConfig CBIT_3 +============= ================ + +The read/write mode selects the width of the read/write port: + +==== ========== ==================================================== +MODE DATA Width Used WDATA/RDATA Bits +==== ========== ==================================================== +0 16 15, 14, 13, 12, 11, 10, 9, 8, 7, 6, 5, 4, 3, 2, 1, 0 +1 8 14, 12, 10, 8, 6, 4, 2, 0 +2 4 13, 9, 5, 1 +3 2 11, 3 +==== ========== ==================================================== + +The NegClk bit in the RAMB tile (1k die) or RAMT tile (other devices) +negates the polarity of the WCLK port, and the NegClk bit in the RAMT +(1k die) or RAMB tile (other devices) tile negates the polarity of the +RCLK port. + +A logic tile sends the output of its eight logic cells to its neighbour +tiles. A RAM tile does the same thing with the RDATA outputs. Each RAMB +tile exports its RDATA[7:0] outputs and each RAMT tile exports its +RDATA[15:8] outputs via this mechanism. diff --git a/docs/source/ultraplus.rst b/docs/source/ultraplus.rst new file mode 100644 index 0000000..7a0640d --- /dev/null +++ b/docs/source/ultraplus.rst @@ -0,0 +1,759 @@ +UltraPlus Features Documentation +================================ + +The ice40 UltraPlus devices have a number of new features compared to +the older LP/HX series devices, in particular: + +* Internal DSP units, capable of 16-bit multiply and 32-bit accumulate. +* 1Mbit of extra single-ported RAM, in addition to the usual BRAM +* Internal hard IP cores for I2C and SPI +* 2 internal oscillators, 48MHz (with divider) and 10kHz +* 24mA constant current LED ouputs and PWM hard IP + +In order to implement these new features, a significant architecural +change has been made: the left and right sides of the device are no +longer IO, but instead DSP and IPConnect tiles. + +Currently icestorm and arachne-pnr support the DSPs (except for +cascading), SPRAM , internal oscillators and constant current LED +drivers. Work to support the remaining features is underway. + +DSP Tiles +--------- + +Each MAC16 DSP comprises of 4 DSP tiles, all of which perform part of +the DSP function and have different routing bit configurations. +Structually they are similar to logic tiles, but with the DSP function +wired into where the LUTs and DFFs would be. The four types of DSP tiles +will be referred to as DSP0 through DSP3, with DSP0 at the lowest +y-position. One signal CO, is also routed through the IPConnect tile +above the DSP tile, referred to as IPCON4 in this context. The location +of signals and configuration bits is documented below. + +| **Signal Assignments** + ++----------+----------+----------+----------+----------+----------+ +| SB_MAC16 | DSP0 | DSP1 | DSP2 | DSP3 | IPCON4 | +| port | | | | | | ++==========+==========+==========+==========+==========+==========+ +| CLK | -- | -- | lutff_gl | -- | -- | +| | | | obal/clk | | | ++----------+----------+----------+----------+----------+----------+ +| CE | -- | -- | lutff_gl | -- | -- | +| | | | obal/cen | | | ++----------+----------+----------+----------+----------+----------+ +| C[7:0] | -- | -- | -- | l | -- | +| | | | | utff\_[7 | | +| | | | | :0]/in_3 | | ++----------+----------+----------+----------+----------+----------+ +| C[15:8] | -- | -- | -- | l | -- | +| | | | | utff\_[7 | | +| | | | | :0]/in_1 | | ++----------+----------+----------+----------+----------+----------+ +| A[7:0] | -- | -- | l | -- | -- | +| | | | utff\_[7 | | | +| | | | :0]/in_3 | | | ++----------+----------+----------+----------+----------+----------+ +| A[15:8] | -- | -- | l | -- | -- | +| | | | utff\_[7 | | | +| | | | :0]/in_1 | | | ++----------+----------+----------+----------+----------+----------+ +| B[7:0] | -- | l | -- | -- | -- | +| | | utff\_[7 | | | | +| | | :0]/in_3 | | | | ++----------+----------+----------+----------+----------+----------+ +| B[15:8] | -- | l | -- | -- | -- | +| | | utff\_[7 | | | | +| | | :0]/in_1 | | | | ++----------+----------+----------+----------+----------+----------+ +| D[7:0] | l | -- | -- | -- | -- | +| | utff\_[7 | | | | | +| | :0]/in_3 | | | | | ++----------+----------+----------+----------+----------+----------+ +| D[15:8] | l | -- | -- | -- | -- | +| | utff\_[7 | | | | | +| | :0]/in_1 | | | | | ++----------+----------+----------+----------+----------+----------+ +| IRSTTOP | -- | lutff_gl | -- | -- | -- | +| | | obal/s_r | | | | ++----------+----------+----------+----------+----------+----------+ +| IRSTBOT | lutff_gl | -- | -- | -- | -- | +| | obal/s_r | | | | | ++----------+----------+----------+----------+----------+----------+ +| ORSTTOP | -- | -- | -- | lutff_gl | -- | +| | | | | obal/s_r | | ++----------+----------+----------+----------+----------+----------+ +| ORSTBOT | -- | -- | lutff_gl | -- | -- | +| | | | obal/s_r | | | ++----------+----------+----------+----------+----------+----------+ +| AHOLD | -- | -- | lutf | -- | -- | +| | | | f_0/in_0 | | | ++----------+----------+----------+----------+----------+----------+ +| BHOLD | -- | lutf | -- | -- | -- | +| | | f_0/in_0 | | | | ++----------+----------+----------+----------+----------+----------+ +| CHOLD | -- | -- | -- | lutf | -- | +| | | | | f_0/in_0 | | ++----------+----------+----------+----------+----------+----------+ +| DHOLD | lutf | -- | -- | -- | -- | +| | f_0/in_0 | | | | | ++----------+----------+----------+----------+----------+----------+ +| OHOLDTOP | -- | -- | -- | lutf | -- | +| | | | | f_1/in_0 | | ++----------+----------+----------+----------+----------+----------+ +| OHOLDBOT | lutf | -- | -- | -- | -- | +| | f_1/in_0 | | | | | ++----------+----------+----------+----------+----------+----------+ +| A | -- | -- | -- | lutf | -- | +| DDSUBTOP | | | | f_3/in_0 | | ++----------+----------+----------+----------+----------+----------+ +| A | lutf | -- | -- | -- | -- | +| DDSUBBOT | f_3/in_0 | | | | | ++----------+----------+----------+----------+----------+----------+ +| OLOADTOP | -- | -- | -- | lutf | -- | +| | | | | f_2/in_0 | | ++----------+----------+----------+----------+----------+----------+ +| OLOADBOT | lutf | -- | -- | -- | -- | +| | f_2/in_0 | | | | | ++----------+----------+----------+----------+----------+----------+ +| CI | lutf | -- | -- | -- | -- | +| | f_4/in_0 | | | | | ++----------+----------+----------+----------+----------+----------+ +| O[31:0] | mult/ | mult/O | mult/O\ | mult/O\ | -- | +| | O\_[7:0] | \_[15:8] | _[23:16] | _[31:24] | | ++----------+----------+----------+----------+----------+----------+ +| CO | -- | -- | -- | -- | slf_op_0 | ++----------+----------+----------+----------+----------+----------+ + +| **Configuration Bits** + +The DSP configuration bits mostly follow the order stated in the ICE +Technology Library document, where they are described as CBIT[24:0]. For +most DSP tiles, these follow a logical order where CBIT[7:0] maps to +DSP0 CBIT[7:0]; CBIT[15:8] to DSP1 CBIT[7:0], CBIT[23:16] to DSP2 +CBIT[7:0] and CBIT[24] to DSP3 CBIT0. + +However, there is one location where configuration bits are swapped +between DSP tiles and IPConnect tiles. In DSP1 (0, 16) CBIT[4:1] are +used for IP such as the internal oscillator, and the DSP configuration +bits are then located in IPConnect tile (0, 19) CBIT[6:3]. + +The full list of configuration bits, including the changes for the DSP +at (0, 15) are described in the table below. + ++-----------------------+-----------------------+-----------------------+ +| Parameter | Normal Position | DSP (0, 15) | +| | | Changes | ++=======================+=======================+=======================+ +| C_REG | DSP0.CBIT_0 | | ++-----------------------+-----------------------+-----------------------+ +| A_REG | DSP0.CBIT_1 | | ++-----------------------+-----------------------+-----------------------+ +| B_REG | DSP0.CBIT_2 | | ++-----------------------+-----------------------+-----------------------+ +| D_REG | DSP0.CBIT_3 | | ++-----------------------+-----------------------+-----------------------+ +| TOP_8x8_MULT_REG | DSP0.CBIT_4 | | ++-----------------------+-----------------------+-----------------------+ +| BOT_8x8_MULT_REG | DSP0.CBIT_5 | | ++-----------------------+-----------------------+-----------------------+ +| PIP | DSP0.CBIT_6 | | +| ELINE_16x16_MULT_REG1 | | | ++-----------------------+-----------------------+-----------------------+ +| PIP | DSP0.CBIT_7 | | +| ELINE_16x16_MULT_REG2 | | | ++-----------------------+-----------------------+-----------------------+ +| TOPOUTPUT_SELECT[0] | DSP1.CBIT_0 | | ++-----------------------+-----------------------+-----------------------+ +| TOPOUTPUT_SELECT[1] | DSP1.CBIT_1 | (0, 19).CBIT_3 | ++-----------------------+-----------------------+-----------------------+ +| TOPA | DSP1.CBIT\_[3:2] | (0, 19).CBIT\_[5:4] | +| DDSUB_LOWERINPUT[1:0] | | | ++-----------------------+-----------------------+-----------------------+ +| TOPADDSUB_UPPERINUT | DSP1.CBIT_4 | (0, 19).CBIT_6 | ++-----------------------+-----------------------+-----------------------+ +| TOPAD | DSP1.CBIT\_[6:5] | | +| DSUB_CARRYSELECT[1:0] | | | ++-----------------------+-----------------------+-----------------------+ +| BOTOUTPUT_SELECT[0] | DSP1.CBIT_7 | | ++-----------------------+-----------------------+-----------------------+ +| BOTOUTPUT_SELECT[1] | DSP2.CBIT_0 | | ++-----------------------+-----------------------+-----------------------+ +| BOTA | DSP2.CBIT\_[2:1] | | +| DDSUB_LOWERINPUT[1:0] | | | ++-----------------------+-----------------------+-----------------------+ +| BOTADDSUB_UPPERINPUT | DSP2.CBIT_3 | | ++-----------------------+-----------------------+-----------------------+ +| BOTAD | DSP2.CBIT\_[5:4] | | +| DSUB_CARRYSELECT[1:0] | | | ++-----------------------+-----------------------+-----------------------+ +| MODE_8x8 | DSP2.CBIT_6 | | ++-----------------------+-----------------------+-----------------------+ +| A_SIGNED | DSP2.CBIT_7 | | ++-----------------------+-----------------------+-----------------------+ +| B_SIGNED | DSP3.CBIT_0 | | ++-----------------------+-----------------------+-----------------------+ + +Lattice document a limited number of supported configurations in the ICE +Technology Library document, and Lattice's EDIF parser will reject +designs not following a supported configuration. It is not yet known +whether unsupported configurations (such as mixed signed and unsigned) +function correctly or not. + +| **Other Implementation Notes** + +| All active DSP tiles, and all IPConnect tiles whether used or not, + have some bits set which reflect their logic tile heritage. The + LC\_\ x bits which would be used to configure the logic cell, are set + to the below pattern for each "logic cell" (interpreting them like a + logic tile): +| 0000111100001111 0000 +| Coincidentally or not, this corresponds to a buffer passing through + input 2 to the output. For each "cell" the cascade bit + LC0\ x\ \_inmux02_5 is also set, effectively creating one large chain, + as this connects input 2 to the output of the previous LUT. The DSPs + at least will not function unless these bits are set correctly, so + they + +have some purpose and presumably indicate that the remains of a LUT are +still present. There does not seem to be any case under which iCEcube +generates a pattern other than this though. + +IPConnect Tiles +--------------- + +IPConnect tiles are used for connections to all of the other UltraPlus +features, such as I2C/SPI, SPRAM, RGB and oscillators. Like DSP tiles, +they are structually similar to logic tiles. The outputs of IP functions +are connected to nets named slf_op_0 through slf_op_7, and the inputs +use the LUT/FF inputs in the same way as DSP tiles. + +Internal Oscillators +-------------------- + +Both of the internal oscillators are connected through IPConnect tiles, +with their outputs optionally connected to the global networks, by +setting the "padin" extra bit (the used global networks 4 and 5 don't +have physical pins on UltraPlus devices). + +SB_HFOSC +~~~~~~~~ + +| The CLKHFPU input connects through IPConnect tile (0, 29) input + lutff_0/in_1; and the CLKHFEN input connects through input + lutff_7/in_3 of the same tile. +| The CLKHF output of SB_HFOSC is connected to both IPConnect tile (0, + 28) output slf_op_7 and to the padin of glb_netwk_4. + +Configuration bit CLKHF_DIV[1] maps to DSP1 tile (0, 16) config bit +CBIT_4, and CLKHF_DIV[0] maps to DSP1 tile (0, 16) config bit CBIT_3. + +There is also an undocumented trimming function of the HFOSC, using the +ports TRIM0 through TRIM9. This can only be accessed directly in iCECUBE +if you modify the standard cell library. However if you set the +attribute VPP_2V5_TO_1P8V (which itself is not that well documented +either) to 1 on the top level module, then the configuration bit CBIT_5 +of (0, 16) is set; and TRIM8 and TRIM4 are connected to the same net as +CLKHFPU. + +TRIM[3:0] connect to (25, 28, lutff\_[7:4]/in_0) and TRIM[9:4] connect +to (25, 29, lutff\_[5:0]/in_3). CBIT_5 of (0, 16) must be set to enable +trimming. The trim range on the device used for testing was from 30.1 to +75.9 MHz. TRIM9 seemed to have no effect, the other inputs could broadly +be considered to form a binary word, however it appeared neither linear +nor even monotonic. + +SB_LFOSC +~~~~~~~~ + +| The CLKLFPU input connects through IPConnect tile (25, 29) input + lutff_0/in_1; and the CLKLFEN input connects through input + lutff_7/in_3 of the same tile. +| The CLKLF output of SB_LFOSC is connected to both IPConnect tile (25, + 29) output slf_op_0 and to the padin of glb_netwk_5. + +SB_LFOSC has no configuration bits. + +SPRAM +----- + +The UltraPlus devices have 1Mbit of extra single-ported RAM, split into +4 256kbit blocks. The full list of connections for each SPRAM block in +the 5k device is shown below, as well as the location of the 1 +configuration bit which is set to enable use of that SPRAM block. + ++-------------+-------------+-------------+-------------+-------------+ +| Signal | SPRAM (0, | SPRAM (0, | SPRAM (25, | SPRAM (25, | +| | 0, 1) | 0, 2) | 0, 3) | 0, 4) | ++=============+=============+=============+=============+=============+ +| A | (0, 2, | (0, 2, | (25, 2, | (25, 2, | +| DDRESS[1:0] | lutff\_ | lutff\_ | lutff\_ | lutff\_ | +| | [1:0]/in_1) | [7:6]/in_0) | [1:0]/in_1) | [7:6]/in_0) | ++-------------+-------------+-------------+-------------+-------------+ +| A | (0, 2, | (0, 3, | (25, 2, | (25, 3, | +| DDRESS[7:2] | lutff\_ | lutff\_ | lutff\_ | lutff\_ | +| | [7:2]/in_1) | [5:0]/in_3) | [7:2]/in_1) | [5:0]/in_3) | ++-------------+-------------+-------------+-------------+-------------+ +| A | (0, 2, | (0, 3, | (25, 2, | (25, 3, | +| DDRESS[9:8] | lutff\_ | lutff\_ | lutff\_ | lutff\_ | +| | [1:0]/in_0) | [7:6]/in_3) | [1:0]/in_0) | [7:6]/in_3) | ++-------------+-------------+-------------+-------------+-------------+ +| ADD | (0, 2, | (0, 3, | (25, 2, | (25, 3, | +| RESS[13:10] | lutff\_ | lutff\_ | lutff\_ | lutff\_ | +| | [5:2]/in_0) | [3:0]/in_1) | [5:2]/in_0) | [3:0]/in_1) | ++-------------+-------------+-------------+-------------+-------------+ +| DATAIN[7:0] | (0, 1, | (0, 1, | (25, 1, | (25, 1, | +| | lutff\_ | lutff\_ | lutff\_ | lutff\_ | +| | [7:0]/in_3) | [7:0]/in_0) | [7:0]/in_3) | [7:0]/in_0) | ++-------------+-------------+-------------+-------------+-------------+ +| D | (0, 1, | (0, 2, | (25, 1, | (25, 2, | +| ATAIN[15:8] | lutff\_ | lutff\_ | lutff\_ | lutff\_ | +| | [7:0]/in_1) | [7:0]/in_3) | [7:0]/in_1) | [7:0]/in_3) | ++-------------+-------------+-------------+-------------+-------------+ +| MA | (0, 3, | (0, 3, | (25, 3, | (25, 3, | +| SKWREN[3:0] | lutff\_ | lutff\_ | lutff\_ | lutff\_ | +| | [3:0]/in_0) | [7:4]/in_0) | [3:0]/in_0) | [7:4]/in_0) | ++-------------+-------------+-------------+-------------+-------------+ +| WREN | (0, 3, | (0, 3, | (25, 3, | (25, 3, | +| | lu | lu | lu | lu | +| | tff_4/in_1) | tff_5/in_1) | tff_4/in_1) | tff_5/in_1) | ++-------------+-------------+-------------+-------------+-------------+ +| CHIPSELECT | (0, 3, | (0, 3, | (25, 3, | (25, 3, | +| | lu | lu | lu | lu | +| | tff_6/in_1) | tff_7/in_1) | tff_6/in_1) | tff_7/in_1) | ++-------------+-------------+-------------+-------------+-------------+ +| CLOCK | (0, 1, clk) | (0, 2, clk) | (25, 1, | (25, 2, | +| | | | clk) | clk) | ++-------------+-------------+-------------+-------------+-------------+ +| STANDBY | (0, 4, | (0, 4, | (25, 4, | (25, 4, | +| | lu | lu | lu | lu | +| | tff_0/in_3) | tff_1/in_3) | tff_0/in_3) | tff_1/in_3) | ++-------------+-------------+-------------+-------------+-------------+ +| SLEEP | (0, 4, | (0, 4, | (25, 4, | (25, 4, | +| | lu | lu | lu | lu | +| | tff_2/in_3) | tff_3/in_3) | tff_2/in_3) | tff_3/in_3) | ++-------------+-------------+-------------+-------------+-------------+ +| POWEROFF | (0, 4, | (0, 4, | (25, 4, | (25, 4, | +| | lu | lu | lu | lu | +| | tff_4/in_3) | tff_5/in_3) | tff_4/in_3) | tff_5/in_3) | ++-------------+-------------+-------------+-------------+-------------+ +| D | (0, 1, | (0, 3, | (25, 1, | (25, 3, | +| ATAOUT[7:0] | slf | slf | slf | slf | +| | _op\_[7:0]) | _op\_[7:0]) | _op\_[7:0]) | _op\_[7:0]) | ++-------------+-------------+-------------+-------------+-------------+ +| DA | (0, 2, | (0, 4, | (25, 2, | (25, 4, | +| TAOUT[15:8] | slf | slf | slf | slf | +| | _op\_[7:0]) | _op\_[7:0]) | _op\_[7:0]) | _op\_[7:0]) | ++-------------+-------------+-------------+-------------+-------------+ +| *SP | *(0, 1, | *(0, 1, | *(25, 1, | *(25, 1, | +| RAM_ENABLE* | CBIT_0)* | CBIT_1)* | CBIT_0)* | CBIT_1)* | ++-------------+-------------+-------------+-------------+-------------+ + +RGB LED Driver +-------------- + +The UltraPlus devices contain an internal 3-channel 2-24mA +constant-current driver intended for RGB led driving (SB_RGBA_DRV). It +is broken out onto 3 pins: 39, 40 and 41 on the QFN48 package. The LED +driver is implemented using the IPConnect tiles and is entirely seperate +to the IO cells, if the LED driver is ignored or disabled on a pin then +the pin can be used as an open-drain IO using the standard IO cell. + +Note that the UltraPlus devices also have a seperate PWM generator IP +core, which would often be connected to this one to create LED effects +such as "breathing" without involving FPGA resources. + +The LED driver connections are shown in the label below. + +======== ====================== +Signal Net +======== ====================== +CURREN (25, 29, lutff_6/in_3) +RGBLEDEN (0, 30, lutff_1/in_1) +RGB0PWM (0, 30, lutff_2/in_1) +RGB1PWM (0, 30, lutff_3/in_1) +RGB2PWM (0, 30, lutff_4/in_1) +======== ====================== + +The configuration bits are as follows. As well as the documented bits, +another bit RGBA_DRV_EN is set if any of the channels are enabled. + +================= ==================== +Parameter Bit +================= ==================== +RGBA_DRV_EN (0, 28, CBIT_5) +RGB0_CURRENT[1:0] (0, 28, CBIT\_[7:6]) +RGB0_CURRENT[5:2] (0, 29, CBIT\_[3:0]) +RGB1_CURRENT[3:0] (0, 29, CBIT\_[7:4]) +RGB1_CURRENT[5:4] (0, 30, CBIT\_[1:0]) +RGB2_CURRENT[5:0] (0, 30, CBIT\_[7:2]) +CURRENT_MODE (0, 28, CBIT_4) +================= ==================== + +IO Changes +---------- + +The IO tiles contain a few new bits compared to earlier ice40 devices. +The bits padeb_test_0 and padeb_test_1 are set for all pins, even unused +ones, unless set as an output. + +There are also some new bits used to control the pullup strength: + ++-----------------------+-----------------------+-----------------------+ +| Strength | Cell 0 | Cell 1 | ++=======================+=======================+=======================+ +| 3.3kΩ | cf_bit_32 | cf_bit_36 | +| | B7[10] | B13[10] | ++-----------------------+-----------------------+-----------------------+ +| 6.8kΩ | cf_bit_33 | cf_bit_37 | +| | B6[10] | B12[10] | ++-----------------------+-----------------------+-----------------------+ +| 10kΩ | cf_bit_34 | cf_bit_38 | +| | B7[15] | B13[15] | ++-----------------------+-----------------------+-----------------------+ +| 100kΩ | !cf_bit_35 | !cf_bit_39 | +| (default) | !B6[15] | !B12[15] | ++-----------------------+-----------------------+-----------------------+ + +I\ :sup:`3`\ C capable IO +~~~~~~~~~~~~~~~~~~~~~~~~~ + +The UltraPlus devices have two IO pins designed for the new MIPI +I\ :sup:`3`\ C standard (pins 23 and 25 in the SG48 package), compared +to normal IO pins they have two switchable pullups each. One of these +pullups, the weak pullup, is fixed at 100k and the other can be set to +3.3k, 6.8k or 10k using the mechanism above. The pullup control signals +do not connect directly to the IO tile, but instead connect through an +IPConnect tile. + +The connections are listed below: + ++-----------------------+-----------------------+-----------------------+ +| Signal | Pin 23 | Pin 25 | +| | (19, 31, 0) | (19, 31, 1) | ++=======================+=======================+=======================+ +| PU_ENB | (25, 27, | (25, 27, | +| | lutff_6/in_0) | lutff_7/in_0) | ++-----------------------+-----------------------+-----------------------+ +| WEAK_PU_ENB | (25, 27, | (25, 27, | +| | lutff_4/in_0) | lutff_5/in_0) | ++-----------------------+-----------------------+-----------------------+ + +Hard IP +------- + +The UltraPlus devices contain three types of Hard IP: I\ :sup:`2`\ C +(SB_I2C), SPI (SB_SPI), and LED PWM generation (SB_LEDDA_IP). The +connections and configurations for each of these blocks are documented +below. Names in italics are parameters rather than actual bits, where +multiple bits are used to enable an IP they are labeled as \_ENABLE_0, +\_ENABLE_1, etc. + ++-----------------------+-----------------------+-----------------------+ +| Signal | I2C | I2C | +| | (0, 31, 0) | (25, 31, 0) | ++=======================+=======================+=======================+ +| SBACKO | (0, 30, slf_op_6) | (25, 30, slf_op_6) | ++-----------------------+-----------------------+-----------------------+ +| SBADRI0 | (0, 30, lutff_1/in_0) | (25, 30, | +| | | lutff_1/in_0) | ++-----------------------+-----------------------+-----------------------+ +| SBADRI1 | (0, 30, lutff_2/in_0) | (25, 30, | +| | | lutff_2/in_0) | ++-----------------------+-----------------------+-----------------------+ +| SBADRI2 | (0, 30, lutff_3/in_0) | (25, 30, | +| | | lutff_3/in_0) | ++-----------------------+-----------------------+-----------------------+ +| SBADRI3 | (0, 30, lutff_4/in_0) | (25, 30, | +| | | lutff_4/in_0) | ++-----------------------+-----------------------+-----------------------+ +| SBADRI4 | (0, 30, lutff_5/in_0) | (25, 30, | +| | | lutff_5/in_0) | ++-----------------------+-----------------------+-----------------------+ +| SBADRI5 | (0, 30, lutff_6/in_0) | (25, 30, | +| | | lutff_6/in_0) | ++-----------------------+-----------------------+-----------------------+ +| SBADRI6 | (0, 30, lutff_7/in_0) | (25, 30, | +| | | lutff_7/in_0) | ++-----------------------+-----------------------+-----------------------+ +| SBADRI7 | (0, 29, lutff_2/in_0) | (25, 29, | +| | | lutff_2/in_0) | ++-----------------------+-----------------------+-----------------------+ +| SBCLKI | (0, 30, clk) | (25, 30, clk) | ++-----------------------+-----------------------+-----------------------+ +| SBDATI0 | (0, 29, lutff_5/in_0) | (25, 29, | +| | | lutff_5/in_0) | ++-----------------------+-----------------------+-----------------------+ +| SBDATI1 | (0, 29, lutff_6/in_0) | (25, 29, | +| | | lutff_6/in_0) | ++-----------------------+-----------------------+-----------------------+ +| SBDATI2 | (0, 29, lutff_7/in_0) | (25, 29, | +| | | lutff_7/in_0) | ++-----------------------+-----------------------+-----------------------+ +| SBDATI3 | (0, 30, lutff_0/in_3) | (25, 30, | +| | | lutff_0/in_3) | ++-----------------------+-----------------------+-----------------------+ +| SBDATI4 | (0, 30, lutff_5/in_1) | (25, 30, | +| | | lutff_5/in_1) | ++-----------------------+-----------------------+-----------------------+ +| SBDATI5 | (0, 30, lutff_6/in_1) | (25, 30, | +| | | lutff_6/in_1) | ++-----------------------+-----------------------+-----------------------+ +| SBDATI6 | (0, 30, lutff_7/in_1) | (25, 30, | +| | | lutff_7/in_1) | ++-----------------------+-----------------------+-----------------------+ +| SBDATI7 | (0, 30, lutff_0/in_0) | (25, 30, | +| | | lutff_0/in_0) | ++-----------------------+-----------------------+-----------------------+ +| SBDATO0 | (0, 29, slf_op_6) | (25, 29, slf_op_6) | ++-----------------------+-----------------------+-----------------------+ +| SBDATO1 | (0, 29, slf_op_7) | (25, 29, slf_op_7) | ++-----------------------+-----------------------+-----------------------+ +| SBDATO2 | (0, 30, slf_op_0) | (25, 30, slf_op_0) | ++-----------------------+-----------------------+-----------------------+ +| SBDATO3 | (0, 30, slf_op_1) | (25, 30, slf_op_1) | ++-----------------------+-----------------------+-----------------------+ +| SBDATO4 | (0, 30, slf_op_2) | (25, 30, slf_op_2) | ++-----------------------+-----------------------+-----------------------+ +| SBDATO5 | (0, 30, slf_op_3) | (25, 30, slf_op_3) | ++-----------------------+-----------------------+-----------------------+ +| SBDATO6 | (0, 30, slf_op_4) | (25, 30, slf_op_4) | ++-----------------------+-----------------------+-----------------------+ +| SBDATO7 | (0, 30, slf_op_5) | (25, 30, slf_op_5) | ++-----------------------+-----------------------+-----------------------+ +| SBRWI | (0, 29, lutff_4/in_0) | (25, 29, | +| | | lutff_4/in_0) | ++-----------------------+-----------------------+-----------------------+ +| SBSTBI | (0, 29, lutff_3/in_0) | (25, 29, | +| | | lutff_3/in_0) | ++-----------------------+-----------------------+-----------------------+ +| I2CIRQ | (0, 30, slf_op_7) | (25, 30, slf_op_7) | ++-----------------------+-----------------------+-----------------------+ +| I2CWKUP | (0, 29, slf_op_5) | (25, 29, slf_op_5) | ++-----------------------+-----------------------+-----------------------+ +| SCLI | (0, 29, lutff_2/in_1) | (25, 29, | +| | | lutff_2/in_1) | ++-----------------------+-----------------------+-----------------------+ +| SCLO | (0, 29, slf_op_3) | (25, 29, slf_op_3) | ++-----------------------+-----------------------+-----------------------+ +| SCLOE | (0, 29, slf_op_4) | (25, 29, slf_op_4) | ++-----------------------+-----------------------+-----------------------+ +| SDAI | (0, 29, lutff_1/in_1) | (25, 29, | +| | | lutff_1/in_1) | ++-----------------------+-----------------------+-----------------------+ +| SDAO | (0, 29, slf_op_1) | (25, 29, slf_op_1) | ++-----------------------+-----------------------+-----------------------+ +| SDAOE | (0, 29, slf_op_2) | (25, 29, slf_op_2) | ++-----------------------+-----------------------+-----------------------+ +| *I2C_ENABLE_0* | *(13, 31, | *(19, 31, | +| | cbit2usealt_in_0)* | cbit2usealt_in_0)* | ++-----------------------+-----------------------+-----------------------+ +| *I2C_ENABLE_1* | *(12, 31, | *(19, 31, | +| | cbit2usealt_in_1)* | cbit2usealt_in_1)* | ++-----------------------+-----------------------+-----------------------+ +| *SDA_INPUT_DELAYED* | *(12, 31, | *(19, 31, | +| | SDA_input_delay)* | SDA_input_delay)* | ++-----------------------+-----------------------+-----------------------+ +| *SDA_OUTPUT_DELAYED* | *(12, 31, | *(19, 31, | +| | SDA_output_delay)* | SDA_output_delay)* | ++-----------------------+-----------------------+-----------------------+ + ++-----------------------+-----------------------+-----------------------+ +| Signal | SPI | SPI | +| | (0, 0, 0) | (25, 0, 1) | ++=======================+=======================+=======================+ +| SBACKO | (0, 20, slf_op_1) | (25, 20, slf_op_1) | ++-----------------------+-----------------------+-----------------------+ +| SBADRI0 | (0, 19, lutff_1/in_1) | (25, 19, | +| | | lutff_1/in_1) | ++-----------------------+-----------------------+-----------------------+ +| SBADRI1 | (0, 19, lutff_2/in_1) | (25, 19, | +| | | lutff_2/in_1) | ++-----------------------+-----------------------+-----------------------+ +| SBADRI2 | (0, 20, lutff_0/in_3) | (25, 20, | +| | | lutff_0/in_3) | ++-----------------------+-----------------------+-----------------------+ +| SBADRI3 | (0, 20, lutff_1/in_3) | (25, 20, | +| | | lutff_1/in_3) | ++-----------------------+-----------------------+-----------------------+ +| SBADRI4 | (0, 20, lutff_2/in_3) | (25, 20, | +| | | lutff_2/in_3) | ++-----------------------+-----------------------+-----------------------+ +| SBADRI5 | (0, 20, lutff_3/in_3) | (25, 20, | +| | | lutff_3/in_3) | ++-----------------------+-----------------------+-----------------------+ +| SBADRI6 | (0, 20, lutff_4/in_3) | (25, 20, | +| | | lutff_4/in_3) | ++-----------------------+-----------------------+-----------------------+ +| SBADRI7 | (0, 20, lutff_5/in_3) | (25, 20, | +| | | lutff_5/in_3) | ++-----------------------+-----------------------+-----------------------+ +| SBCLKI | (0, 20, clk) | (25, 20, clk) | ++-----------------------+-----------------------+-----------------------+ +| SBDATI0 | (0, 19, lutff_1/in_3) | (25, 19, | +| | | lutff_1/in_3) | ++-----------------------+-----------------------+-----------------------+ +| SBDATI1 | (0, 19, lutff_2/in_3) | (25, 19, | +| | | lutff_2/in_3) | ++-----------------------+-----------------------+-----------------------+ +| SBDATI2 | (0, 19, lutff_3/in_3) | (25, 19, | +| | | lutff_3/in_3) | ++-----------------------+-----------------------+-----------------------+ +| SBDATI3 | (0, 19, lutff_4/in_3) | (25, 19, | +| | | lutff_4/in_3) | ++-----------------------+-----------------------+-----------------------+ +| SBDATI4 | (0, 19, lutff_5/in_3) | (25, 19, | +| | | lutff_5/in_3) | ++-----------------------+-----------------------+-----------------------+ +| SBDATI5 | (0, 19, lutff_6/in_3) | (25, 19, | +| | | lutff_6/in_3) | ++-----------------------+-----------------------+-----------------------+ +| SBDATI6 | (0, 19, lutff_7/in_3) | (25, 19, | +| | | lutff_7/in_3) | ++-----------------------+-----------------------+-----------------------+ +| SBDATI7 | (0, 19, lutff_0/in_1) | (25, 19, | +| | | lutff_0/in_1) | ++-----------------------+-----------------------+-----------------------+ +| SBDATO0 | (0, 19, slf_op_1) | (25, 19, slf_op_1) | ++-----------------------+-----------------------+-----------------------+ +| SBDATO1 | (0, 19, slf_op_2) | (25, 19, slf_op_2) | ++-----------------------+-----------------------+-----------------------+ +| SBDATO2 | (0, 19, slf_op_3) | (25, 19, slf_op_3) | ++-----------------------+-----------------------+-----------------------+ +| SBDATO3 | (0, 19, slf_op_4) | (25, 19, slf_op_4) | ++-----------------------+-----------------------+-----------------------+ +| SBDATO4 | (0, 19, slf_op_5) | (25, 19, slf_op_5) | ++-----------------------+-----------------------+-----------------------+ +| SBDATO5 | (0, 19, slf_op_6) | (25, 19, slf_op_6) | ++-----------------------+-----------------------+-----------------------+ +| SBDATO6 | (0, 19, slf_op_7) | (25, 19, slf_op_7) | ++-----------------------+-----------------------+-----------------------+ +| SBDATO7 | (0, 20, slf_op_0) | (25, 20, slf_op_0) | ++-----------------------+-----------------------+-----------------------+ +| SBRWI | (0, 19, lutff_0/in_3) | (25, 19, | +| | | lutff_0/in_3) | ++-----------------------+-----------------------+-----------------------+ +| SBSTBI | (0, 20, lutff_6/in_3) | (25, 20, | +| | | lutff_6/in_3) | ++-----------------------+-----------------------+-----------------------+ +| MCSNO0 | (0, 21, slf_op_2) | (25, 21, slf_op_2) | ++-----------------------+-----------------------+-----------------------+ +| MCSNO1 | (0, 21, slf_op_4) | (25, 21, slf_op_4) | ++-----------------------+-----------------------+-----------------------+ +| MCSNO2 | (0, 21, slf_op_7) | (25, 21, slf_op_7) | ++-----------------------+-----------------------+-----------------------+ +| MCSNO3 | (0, 22, slf_op_1) | (25, 22, slf_op_1) | ++-----------------------+-----------------------+-----------------------+ +| MCSNOE0 | (0, 21, slf_op_3) | (25, 21, slf_op_3) | ++-----------------------+-----------------------+-----------------------+ +| MCSNOE1 | (0, 21, slf_op_5) | (25, 21, slf_op_5) | ++-----------------------+-----------------------+-----------------------+ +| MCSNOE2 | (0, 22, slf_op_0) | (25, 22, slf_op_0) | ++-----------------------+-----------------------+-----------------------+ +| MCSNOE3 | (0, 22, slf_op_2) | (25, 22, slf_op_2) | ++-----------------------+-----------------------+-----------------------+ +| MI | (0, 22, lutff_0/in_1) | (25, 22, | +| | | lutff_0/in_1) | ++-----------------------+-----------------------+-----------------------+ +| MO | (0, 20, slf_op_6) | (25, 20, slf_op_6) | ++-----------------------+-----------------------+-----------------------+ +| MOE | (0, 20, slf_op_7) | (25, 20, slf_op_7) | ++-----------------------+-----------------------+-----------------------+ +| SCKI | (0, 22, lutff_1/in_1) | (25, 22, | +| | | lutff_1/in_1) | ++-----------------------+-----------------------+-----------------------+ +| SCKO | (0, 21, slf_op_0) | (25, 21, slf_op_0) | ++-----------------------+-----------------------+-----------------------+ +| SCKOE | (0, 21, slf_op_1) | (25, 21, slf_op_1) | ++-----------------------+-----------------------+-----------------------+ +| SCSNI | (0, 22, lutff_2/in_1) | (25, 22, | +| | | lutff_2/in_1) | ++-----------------------+-----------------------+-----------------------+ +| SI | (0, 22, lutff_7/in_3) | (25, 22, | +| | | lutff_7/in_3) | ++-----------------------+-----------------------+-----------------------+ +| SO | (0, 20, slf_op_4) | (25, 20, slf_op_4) | ++-----------------------+-----------------------+-----------------------+ +| SOE | (0, 20, slf_op_5) | (25, 20, slf_op_5) | ++-----------------------+-----------------------+-----------------------+ +| SPIIRQ | (0, 20, slf_op_2) | (25, 20, slf_op_2) | ++-----------------------+-----------------------+-----------------------+ +| SPIWKUP | (0, 20, slf_op_3) | (25, 20, slf_op_3) | ++-----------------------+-----------------------+-----------------------+ +| *SPI_ENABLE_0* | *(7, 0, | *(23, 0, | +| | cbit2usealt_in_0)* | cbit2usealt_in_0)* | ++-----------------------+-----------------------+-----------------------+ +| *SPI_ENABLE_1* | *(7, 0, | *(24, 0, | +| | cbit2usealt_in_1)* | cbit2usealt_in_0)* | ++-----------------------+-----------------------+-----------------------+ +| *SPI_ENABLE_2* | *(6, 0, | *(23, 0, | +| | cbit2usealt_in_0)* | cbit2usealt_in_1)* | ++-----------------------+-----------------------+-----------------------+ +| *SPI_ENABLE_3* | *(6, 0, | *(24, 0, | +| | cbit2usealt_in_1)* | cbit2usealt_in_1)* | ++-----------------------+-----------------------+-----------------------+ + ++-----------------------------------+-----------------------------------+ +| Signal | LEDDA_IP | +| | (0, 31, 2) | ++===================================+===================================+ +| LEDDADDR0 | (0, 28, lutff_4/in_0) | ++-----------------------------------+-----------------------------------+ +| LEDDADDR1 | (0, 28, lutff_5/in_0) | ++-----------------------------------+-----------------------------------+ +| LEDDADDR2 | (0, 28, lutff_6/in_0) | ++-----------------------------------+-----------------------------------+ +| LEDDADDR3 | (0, 28, lutff_7/in_0) | ++-----------------------------------+-----------------------------------+ +| LEDDCLK | (0, 29, clk) | ++-----------------------------------+-----------------------------------+ +| LEDDCS | (0, 28, lutff_2/in_0) | ++-----------------------------------+-----------------------------------+ +| LEDDDAT0 | (0, 28, lutff_2/in_1) | ++-----------------------------------+-----------------------------------+ +| LEDDDAT1 | (0, 28, lutff_3/in_1) | ++-----------------------------------+-----------------------------------+ +| LEDDDAT2 | (0, 28, lutff_4/in_1) | ++-----------------------------------+-----------------------------------+ +| LEDDDAT3 | (0, 28, lutff_5/in_1) | ++-----------------------------------+-----------------------------------+ +| LEDDDAT4 | (0, 28, lutff_6/in_1) | ++-----------------------------------+-----------------------------------+ +| LEDDDAT5 | (0, 28, lutff_7/in_1) | ++-----------------------------------+-----------------------------------+ +| LEDDDAT6 | (0, 28, lutff_0/in_0) | ++-----------------------------------+-----------------------------------+ +| LEDDDAT7 | (0, 28, lutff_1/in_0) | ++-----------------------------------+-----------------------------------+ +| LEDDDEN | (0, 28, lutff_1/in_1) | ++-----------------------------------+-----------------------------------+ +| LEDDEXE | (0, 28, lutff_0/in_1) | ++-----------------------------------+-----------------------------------+ +| LEDDON | (0, 29, slf_op_0) | ++-----------------------------------+-----------------------------------+ +| PWMOUT0 | (0, 28, slf_op_4) | ++-----------------------------------+-----------------------------------+ +| PWMOUT1 | (0, 28, slf_op_5) | ++-----------------------------------+-----------------------------------+ +| PWMOUT2 | (0, 28, slf_op_6) | ++-----------------------------------+-----------------------------------+ + +The I\ :sup:`2`\ C "glitch filter" (referred to as SB_FILTER_50NS) is a +seperate module from the I\ :sup:`2`\ C interface IP, with connections +as shown below: + ++-----------------------+-----------------------+-----------------------+ +| Signal | SB_FILTER_50NS | SB_FILTER_50NS | +| | (25, 31, 2) | (25, 31, 3) | ++=======================+=======================+=======================+ +| FILTERIN | (25, 27, | (25, 27, | +| | lutff_1/in_0) | lutff_0/in_0) | ++-----------------------+-----------------------+-----------------------+ +| FILTEROUT | (25, 27, slf_op_2) | (25, 27, slf_op_1) | ++-----------------------+-----------------------+-----------------------+ +| ENABLE_0 | (25, 30, CBIT_2) | (25, 30, CBIT_5) | ++-----------------------+-----------------------+-----------------------+ +| ENABLE_1 | (25, 30, CBIT_3) | (25, 30, CBIT_6) | ++-----------------------+-----------------------+-----------------------+ +| ENABLE_2 | (25, 30, CBIT_4) | (25, 30, CBIT_7) | ++-----------------------+-----------------------+-----------------------+ diff --git a/docs/ultraplus.html b/docs/ultraplus.html deleted file mode 100644 index 11e249d..0000000 --- a/docs/ultraplus.html +++ /dev/null @@ -1,450 +0,0 @@ - - - -Project IceStorm – UltraPlus Features Documentation - -

Project IceStorm – UltraPlus Features Documentation

- -

-Project IceStorm aims at documenting the bitstream format of Lattice iCE40 -FPGAs and providing simple tools for analyzing and creating bitstream files. -This is work in progress. -

- -

The ice40 UltraPlus devices have a number of new features compared to the older LP/HX series - devices, in particular: -

    -
  • Internal DSP units, capable of 16-bit multiply and 32-bit accumulate.
    • -
  • 1Mbit of extra single-ported RAM, in addition to the usual BRAM
    • -
  • Internal hard IP cores for I2C and SPI
    • -
  • 2 internal oscillators, 48MHz (with divider) and 10kHz
    • -
  • 24mA constant current LED ouputs and PWM hard IP
    • -
- In order to implement these new features, a significant architecural change has been made: the - left and right sides of the device are no longer IO, but instead DSP and IPConnect tiles. - -

- -

Currently icestorm and arachne-pnr support the DSPs (except for cascading), SPRAM , internal oscillators and constant current - LED drivers. Work to support the remaining features is underway.

- -

DSP Tiles

-

Each MAC16 DSP comprises of 4 DSP tiles, all of which perform part of the DSP function and have -different routing bit configurations. Structually they are similar to logic tiles, but with the DSP -function wired into where the LUTs and DFFs would be. The four types of DSP tiles will be referred to -as DSP0 through DSP3, with DSP0 at the lowest y-position. One signal CO, is also routed through the -IPConnect tile above the DSP tile, referred to as IPCON4 in this context. - -The location of signals and configuration bits is documented below.

-

-Signal Assignments
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
SB_MAC16 portDSP0DSP1DSP2DSP3IPCON4
CLK--lutff_global/clk--
CE--lutff_global/cen--
C[7:0]---lutff_[7:0]/in_3-
C[15:8]---lutff_[7:0]/in_1-
A[7:0]--lutff_[7:0]/in_3--
A[15:8]--lutff_[7:0]/in_1--
B[7:0]-lutff_[7:0]/in_3---
B[15:8]-lutff_[7:0]/in_1---
D[7:0]lutff_[7:0]/in_3----
D[15:8]lutff_[7:0]/in_1----
IRSTTOP-lutff_global/s_r---
IRSTBOTlutff_global/s_r----
ORSTTOP---lutff_global/s_r-
ORSTBOT--lutff_global/s_r--
AHOLD--lutff_0/in_0--
BHOLD-lutff_0/in_0---
CHOLD---lutff_0/in_0-
DHOLDlutff_0/in_0----
OHOLDTOP---lutff_1/in_0-
OHOLDBOTlutff_1/in_0----
ADDSUBTOP---lutff_3/in_0-
ADDSUBBOTlutff_3/in_0----
OLOADTOP---lutff_2/in_0-
OLOADBOTlutff_2/in_0----
CIlutff_4/in_0----
O[31:0]mult/O_[7:0]mult/O_[15:8]mult/O_[23:16]mult/O_[31:24]-
CO----slf_op_0
- - -

- -

-Configuration Bits
-

The DSP configuration bits mostly follow the order stated in the ICE Technology Library document, where they are described as CBIT[24:0]. For most DSP tiles, - these follow a logical order where CBIT[7:0] maps to DSP0 CBIT[7:0]; CBIT[15:8] - to DSP1 CBIT[7:0], CBIT[23:16] to DSP2 CBIT[7:0] - and CBIT[24] to DSP3 CBIT0. -

-

However, there is one location where configuration bits are swapped between DSP tiles and IPConnect tiles. In DSP1 (0, 16) CBIT[4:1] are used - for IP such as the internal oscillator, and the DSP configuration bits are then located in IPConnect tile (0, 19) CBIT[6:3].

-

The full list of configuration bits, including the changes for the DSP at (0, 15) are described in the table below.

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
ParameterNormal PositionDSP (0, 15)
Changes
C_REGDSP0.CBIT_0
A_REGDSP0.CBIT_1
B_REGDSP0.CBIT_2
D_REGDSP0.CBIT_3
TOP_8x8_MULT_REGDSP0.CBIT_4
BOT_8x8_MULT_REGDSP0.CBIT_5
PIPELINE_16x16_MULT_REG1DSP0.CBIT_6
PIPELINE_16x16_MULT_REG2DSP0.CBIT_7
TOPOUTPUT_SELECT[0]DSP1.CBIT_0
TOPOUTPUT_SELECT[1]DSP1.CBIT_1(0, 19).CBIT_3
TOPADDSUB_LOWERINPUT[1:0]DSP1.CBIT_[3:2](0, 19).CBIT_[5:4]
TOPADDSUB_UPPERINUTDSP1.CBIT_4(0, 19).CBIT_6
TOPADDSUB_CARRYSELECT[1:0]DSP1.CBIT_[6:5]
BOTOUTPUT_SELECT[0]DSP1.CBIT_7
BOTOUTPUT_SELECT[1]DSP2.CBIT_0
BOTADDSUB_LOWERINPUT[1:0]DSP2.CBIT_[2:1]
BOTADDSUB_UPPERINPUTDSP2.CBIT_3
BOTADDSUB_CARRYSELECT[1:0]DSP2.CBIT_[5:4]
MODE_8x8DSP2.CBIT_6
A_SIGNEDDSP2.CBIT_7
B_SIGNEDDSP3.CBIT_0
- -

Lattice document a limited number of supported configurations in the ICE Technology Library document, and Lattice's EDIF parser will - reject designs not following a supported configuration. It is not yet known whether unsupported configurations (such as mixed - signed and unsigned) function correctly or not. - -

-Other Implementation Notes
-

- All active DSP tiles, and all IPConnect tiles whether used or not, have some bits set which reflect their logic tile heritage. The LC_x - bits which would be used to configure the logic cell, are set to the below pattern for each "logic cell" (interpreting them like a logic tile):
-
0000111100001111 0000

- Coincidentally or not, this corresponds to a buffer passing through input 2 to the output. For each "cell" the cascade bit LC0x_inmux02_5 is - also set, effectively creating one large chain, as this connects input 2 to the output of the previous LUT. The DSPs at least will not function unless these bits are set correctly, so they - have some purpose and presumably indicate that the remains of a LUT are still present. There does not seem to be any case under which iCEcube generates a pattern other than this though. -

-

-

IPConnect Tiles

-

IPConnect tiles are used for connections to all of the other UltraPlus features, such as I2C/SPI, SPRAM, RGB and oscillators. Like DSP tiles, -they are structually similar to logic tiles. The outputs of IP functions are connected to nets named slf_op_0 through slf_op_7, -and the inputs use the LUT/FF inputs in the same way as DSP tiles.

- - - -

Internal Oscillators

- -Both of the internal oscillators are connected through IPConnect tiles, with their outputs optionally connected to the global networks, -by setting the "padin" extra bit (the used global networks 4 and 5 don't have physical pins on UltraPlus devices). - -

SB_HFOSC

-

The CLKHFPU input connects through IPConnect tile (0, 29) input lutff_0/in_1; -and the CLKHFEN input connects through input lutff_7/in_3 of the same tile.
- -The CLKHF output of SB_HFOSC is connected to both IPConnect tile (0, 28) output slf_op_7 and to the padin - of glb_netwk_4.

- -

Configuration bit CLKHF_DIV[1] maps to DSP1 tile (0, 16) config bit CBIT_4, and -CLKHF_DIV[0] maps to DSP1 tile (0, 16) config bit CBIT_3.

- -

There is also an undocumented trimming function of the HFOSC, using the ports TRIM0 through TRIM9. This can only be accessed directly in iCECUBE if you modify the standard cell library. However - if you set the attribute VPP_2V5_TO_1P8V (which itself is not that well documented either) to 1 on the top level module, then the configuration bit - CBIT_5 of (0, 16) is set; and TRIM8 and TRIM4 are connected to - the same net as CLKHFPU.

-

TRIM[3:0] connect to (25, 28, lutff_[7:4]/in_0) and TRIM[9:4] - connect to (25, 29, lutff_[5:0]/in_3). CBIT_5 of (0, 16) must be set to enable trimming. The trim range -on the device used for testing was from 30.1 to 75.9 MHz. TRIM9 seemed to have no effect, the other inputs could broadly be considered to form a binary word, however it appeared neither linear -nor even monotonic.

-

SB_LFOSC

-

The CLKLFPU input connects through IPConnect tile (25, 29) input lutff_0/in_1; -and the CLKLFEN input connects through input lutff_7/in_3 of the same tile.
- -The CLKLF output of SB_LFOSC is connected to both IPConnect tile (25, 29) output slf_op_0 and to the padin - of glb_netwk_5.

- -

SB_LFOSC has no configuration bits.

- -

SPRAM

-

The UltraPlus devices have 1Mbit of extra single-ported RAM, split into 4 256kbit blocks. The full list of connections for each SPRAM block in the 5k device is shown below, - as well as the location of the 1 configuration bit which is set to enable use of that SPRAM block.

- - - - - - - - - - - - - - - - - - - -
SignalSPRAM (0, 0, 1)SPRAM (0, 0, 2)SPRAM (25, 0, 3)SPRAM (25, 0, 4)
ADDRESS[1:0](0, 2, lutff_[1:0]/in_1)(0, 2, lutff_[7:6]/in_0)(25, 2, lutff_[1:0]/in_1)(25, 2, lutff_[7:6]/in_0)
ADDRESS[7:2](0, 2, lutff_[7:2]/in_1)(0, 3, lutff_[5:0]/in_3)(25, 2, lutff_[7:2]/in_1)(25, 3, lutff_[5:0]/in_3)
ADDRESS[9:8](0, 2, lutff_[1:0]/in_0)(0, 3, lutff_[7:6]/in_3)(25, 2, lutff_[1:0]/in_0)(25, 3, lutff_[7:6]/in_3)
ADDRESS[13:10](0, 2, lutff_[5:2]/in_0)(0, 3, lutff_[3:0]/in_1)(25, 2, lutff_[5:2]/in_0)(25, 3, lutff_[3:0]/in_1)
DATAIN[7:0](0, 1, lutff_[7:0]/in_3)(0, 1, lutff_[7:0]/in_0)(25, 1, lutff_[7:0]/in_3)(25, 1, lutff_[7:0]/in_0)
DATAIN[15:8](0, 1, lutff_[7:0]/in_1)(0, 2, lutff_[7:0]/in_3)(25, 1, lutff_[7:0]/in_1)(25, 2, lutff_[7:0]/in_3)
MASKWREN[3:0](0, 3, lutff_[3:0]/in_0)(0, 3, lutff_[7:4]/in_0)(25, 3, lutff_[3:0]/in_0)(25, 3, lutff_[7:4]/in_0)
WREN(0, 3, lutff_4/in_1)(0, 3, lutff_5/in_1)(25, 3, lutff_4/in_1)(25, 3, lutff_5/in_1)
CHIPSELECT(0, 3, lutff_6/in_1)(0, 3, lutff_7/in_1)(25, 3, lutff_6/in_1)(25, 3, lutff_7/in_1)
CLOCK(0, 1, clk)(0, 2, clk)(25, 1, clk)(25, 2, clk)
STANDBY(0, 4, lutff_0/in_3)(0, 4, lutff_1/in_3)(25, 4, lutff_0/in_3)(25, 4, lutff_1/in_3)
SLEEP(0, 4, lutff_2/in_3)(0, 4, lutff_3/in_3)(25, 4, lutff_2/in_3)(25, 4, lutff_3/in_3)
POWEROFF(0, 4, lutff_4/in_3)(0, 4, lutff_5/in_3)(25, 4, lutff_4/in_3)(25, 4, lutff_5/in_3)
DATAOUT[7:0](0, 1, slf_op_[7:0])(0, 3, slf_op_[7:0])(25, 1, slf_op_[7:0])(25, 3, slf_op_[7:0])
DATAOUT[15:8](0, 2, slf_op_[7:0])(0, 4, slf_op_[7:0])(25, 2, slf_op_[7:0])(25, 4, slf_op_[7:0])
SPRAM_ENABLE(0, 1, CBIT_0)(0, 1, CBIT_1)(25, 1, CBIT_0)(25, 1, CBIT_1)
- -

RGB LED Driver

-

The UltraPlus devices contain an internal 3-channel 2-24mA constant-current driver intended for RGB led driving (SB_RGBA_DRV). It is broken out onto 3 pins: 39, 40 and 41 on the QFN48 package. -The LED driver is implemented using the IPConnect tiles and is entirely seperate to the IO cells, if the LED driver is ignored or disabled on a pin then the pin -can be used as an open-drain IO using the standard IO cell.

-

Note that the UltraPlus devices also have a seperate PWM generator IP core, which would often be connected to this one to create LED effects such as "breathing" without - involving FPGA resources.

-

The LED driver connections are shown in the label below.

- - - - - - - -
SignalNet
CURREN(25, 29, lutff_6/in_3)
RGBLEDEN(0, 30, lutff_1/in_1)
RGB0PWM(0, 30, lutff_2/in_1)
RGB1PWM(0, 30, lutff_3/in_1)
RGB2PWM(0, 30, lutff_4/in_1)
-

The configuration bits are as follows. As well as the documented bits, another bit RGBA_DRV_EN is set if any of the channels are enabled.

- - - - - - - - - - - -
ParameterBit
RGBA_DRV_EN(0, 28, CBIT_5)
RGB0_CURRENT[1:0](0, 28, CBIT_[7:6])
RGB0_CURRENT[5:2](0, 29, CBIT_[3:0])
RGB1_CURRENT[3:0](0, 29, CBIT_[7:4])
RGB1_CURRENT[5:4](0, 30, CBIT_[1:0])
RGB2_CURRENT[5:0](0, 30, CBIT_[7:2])
CURRENT_MODE(0, 28, CBIT_4)
- -

IO Changes

-

The IO tiles contain a few new bits compared to earlier ice40 devices. - The bits padeb_test_0 and - padeb_test_1 are set for all pins, - even unused ones, unless set as an output.

-

There are also some new bits used to control the pullup strength:

- - - - - - - -
StrengthCell 0Cell 1
3.3kΩcf_bit_32
B7[10]		cf_bit_36
B13[10]
6.8kΩcf_bit_33
B6[10]		cf_bit_37
B12[10]
10kΩcf_bit_34
B7[15]		cf_bit_38
B13[15]
100kΩ
(default)		!cf_bit_35
!B6[15]		!cf_bit_39
!B12[15]
- -

I3C capable IO

-

The UltraPlus devices have two IO pins designed for the new MIPI I3C standard (pins 23 and 25 in the SG48 package), -compared to normal IO pins they have two switchable pullups each. One of these pullups, the weak pullup, is fixed at 100k and the -other can be set to 3.3k, 6.8k or 10k using the mechanism above. The pullup control signals do not -connect directly to the IO tile, but instead connect through an IPConnect tile.

- -

The connections are listed below:

- - - - -
SignalPin 23
(19, 31, 0)		Pin 25
(19, 31, 1)
PU_ENB(25, 27, lutff_6/in_0)(25, 27, lutff_7/in_0)
WEAK_PU_ENB(25, 27, lutff_4/in_0)(25, 27, lutff_5/in_0)
- -

Hard IP

- -

The UltraPlus devices contain three types of Hard IP: I2C (SB_I2C), SPI (SB_SPI), and LED PWM generation -(SB_LEDDA_IP). The connections and configurations for each of these blocks are documented below. Names in italics are parameters rather than actual bits, -where multiple bits are used to enable an IP they are labeled as _ENABLE_0, _ENABLE_1, etc.

-
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
SignalI2C
(0, 31, 0)		I2C
(25, 31, 0)
SBACKO(0, 30, slf_op_6)(25, 30, slf_op_6)
SBADRI0(0, 30, lutff_1/in_0)(25, 30, lutff_1/in_0)
SBADRI1(0, 30, lutff_2/in_0)(25, 30, lutff_2/in_0)
SBADRI2(0, 30, lutff_3/in_0)(25, 30, lutff_3/in_0)
SBADRI3(0, 30, lutff_4/in_0)(25, 30, lutff_4/in_0)
SBADRI4(0, 30, lutff_5/in_0)(25, 30, lutff_5/in_0)
SBADRI5(0, 30, lutff_6/in_0)(25, 30, lutff_6/in_0)
SBADRI6(0, 30, lutff_7/in_0)(25, 30, lutff_7/in_0)
SBADRI7(0, 29, lutff_2/in_0)(25, 29, lutff_2/in_0)
SBCLKI(0, 30, clk)(25, 30, clk)
SBDATI0(0, 29, lutff_5/in_0)(25, 29, lutff_5/in_0)
SBDATI1(0, 29, lutff_6/in_0)(25, 29, lutff_6/in_0)
SBDATI2(0, 29, lutff_7/in_0)(25, 29, lutff_7/in_0)
SBDATI3(0, 30, lutff_0/in_3)(25, 30, lutff_0/in_3)
SBDATI4(0, 30, lutff_5/in_1)(25, 30, lutff_5/in_1)
SBDATI5(0, 30, lutff_6/in_1)(25, 30, lutff_6/in_1)
SBDATI6(0, 30, lutff_7/in_1)(25, 30, lutff_7/in_1)
SBDATI7(0, 30, lutff_0/in_0)(25, 30, lutff_0/in_0)
SBDATO0(0, 29, slf_op_6)(25, 29, slf_op_6)
SBDATO1(0, 29, slf_op_7)(25, 29, slf_op_7)
SBDATO2(0, 30, slf_op_0)(25, 30, slf_op_0)
SBDATO3(0, 30, slf_op_1)(25, 30, slf_op_1)
SBDATO4(0, 30, slf_op_2)(25, 30, slf_op_2)
SBDATO5(0, 30, slf_op_3)(25, 30, slf_op_3)
SBDATO6(0, 30, slf_op_4)(25, 30, slf_op_4)
SBDATO7(0, 30, slf_op_5)(25, 30, slf_op_5)
SBRWI(0, 29, lutff_4/in_0)(25, 29, lutff_4/in_0)
SBSTBI(0, 29, lutff_3/in_0)(25, 29, lutff_3/in_0)
I2CIRQ(0, 30, slf_op_7)(25, 30, slf_op_7)
I2CWKUP(0, 29, slf_op_5)(25, 29, slf_op_5)
SCLI(0, 29, lutff_2/in_1)(25, 29, lutff_2/in_1)
SCLO(0, 29, slf_op_3)(25, 29, slf_op_3)
SCLOE(0, 29, slf_op_4)(25, 29, slf_op_4)
SDAI(0, 29, lutff_1/in_1)(25, 29, lutff_1/in_1)
SDAO(0, 29, slf_op_1)(25, 29, slf_op_1)
SDAOE(0, 29, slf_op_2)(25, 29, slf_op_2)
I2C_ENABLE_0(13, 31, cbit2usealt_in_0)(19, 31, cbit2usealt_in_0)
I2C_ENABLE_1(12, 31, cbit2usealt_in_1)(19, 31, cbit2usealt_in_1)
SDA_INPUT_DELAYED(12, 31, SDA_input_delay)(19, 31, SDA_input_delay)
SDA_OUTPUT_DELAYED(12, 31, SDA_output_delay)(19, 31, SDA_output_delay)
- -		 - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
SignalSPI
(0, 0, 0)		SPI
(25, 0, 1)
SBACKO(0, 20, slf_op_1)(25, 20, slf_op_1)
SBADRI0(0, 19, lutff_1/in_1)(25, 19, lutff_1/in_1)
SBADRI1(0, 19, lutff_2/in_1)(25, 19, lutff_2/in_1)
SBADRI2(0, 20, lutff_0/in_3)(25, 20, lutff_0/in_3)
SBADRI3(0, 20, lutff_1/in_3)(25, 20, lutff_1/in_3)
SBADRI4(0, 20, lutff_2/in_3)(25, 20, lutff_2/in_3)
SBADRI5(0, 20, lutff_3/in_3)(25, 20, lutff_3/in_3)
SBADRI6(0, 20, lutff_4/in_3)(25, 20, lutff_4/in_3)
SBADRI7(0, 20, lutff_5/in_3)(25, 20, lutff_5/in_3)
SBCLKI(0, 20, clk)(25, 20, clk)
SBDATI0(0, 19, lutff_1/in_3)(25, 19, lutff_1/in_3)
SBDATI1(0, 19, lutff_2/in_3)(25, 19, lutff_2/in_3)
SBDATI2(0, 19, lutff_3/in_3)(25, 19, lutff_3/in_3)
SBDATI3(0, 19, lutff_4/in_3)(25, 19, lutff_4/in_3)
SBDATI4(0, 19, lutff_5/in_3)(25, 19, lutff_5/in_3)
SBDATI5(0, 19, lutff_6/in_3)(25, 19, lutff_6/in_3)
SBDATI6(0, 19, lutff_7/in_3)(25, 19, lutff_7/in_3)
SBDATI7(0, 19, lutff_0/in_1)(25, 19, lutff_0/in_1)
SBDATO0(0, 19, slf_op_1)(25, 19, slf_op_1)
SBDATO1(0, 19, slf_op_2)(25, 19, slf_op_2)
SBDATO2(0, 19, slf_op_3)(25, 19, slf_op_3)
SBDATO3(0, 19, slf_op_4)(25, 19, slf_op_4)
SBDATO4(0, 19, slf_op_5)(25, 19, slf_op_5)
SBDATO5(0, 19, slf_op_6)(25, 19, slf_op_6)
SBDATO6(0, 19, slf_op_7)(25, 19, slf_op_7)
SBDATO7(0, 20, slf_op_0)(25, 20, slf_op_0)
SBRWI(0, 19, lutff_0/in_3)(25, 19, lutff_0/in_3)
SBSTBI(0, 20, lutff_6/in_3)(25, 20, lutff_6/in_3)
MCSNO0(0, 21, slf_op_2)(25, 21, slf_op_2)
MCSNO1(0, 21, slf_op_4)(25, 21, slf_op_4)
MCSNO2(0, 21, slf_op_7)(25, 21, slf_op_7)
MCSNO3(0, 22, slf_op_1)(25, 22, slf_op_1)
MCSNOE0(0, 21, slf_op_3)(25, 21, slf_op_3)
MCSNOE1(0, 21, slf_op_5)(25, 21, slf_op_5)
MCSNOE2(0, 22, slf_op_0)(25, 22, slf_op_0)
MCSNOE3(0, 22, slf_op_2)(25, 22, slf_op_2)
MI(0, 22, lutff_0/in_1)(25, 22, lutff_0/in_1)
MO(0, 20, slf_op_6)(25, 20, slf_op_6)
MOE(0, 20, slf_op_7)(25, 20, slf_op_7)
SCKI(0, 22, lutff_1/in_1)(25, 22, lutff_1/in_1)
SCKO(0, 21, slf_op_0)(25, 21, slf_op_0)
SCKOE(0, 21, slf_op_1)(25, 21, slf_op_1)
SCSNI(0, 22, lutff_2/in_1)(25, 22, lutff_2/in_1)
SI(0, 22, lutff_7/in_3)(25, 22, lutff_7/in_3)
SO(0, 20, slf_op_4)(25, 20, slf_op_4)
SOE(0, 20, slf_op_5)(25, 20, slf_op_5)
SPIIRQ(0, 20, slf_op_2)(25, 20, slf_op_2)
SPIWKUP(0, 20, slf_op_3)(25, 20, slf_op_3)
SPI_ENABLE_0(7, 0, cbit2usealt_in_0)(23, 0, cbit2usealt_in_0)
SPI_ENABLE_1(7, 0, cbit2usealt_in_1)(24, 0, cbit2usealt_in_0)
SPI_ENABLE_2(6, 0, cbit2usealt_in_0)(23, 0, cbit2usealt_in_1)
SPI_ENABLE_3(6, 0, cbit2usealt_in_1)(24, 0, cbit2usealt_in_1)
-		 - - - - - - - - - - - - - - - - - - - - - - -
SignalLEDDA_IP
(0, 31, 2)
LEDDADDR0(0, 28, lutff_4/in_0)
LEDDADDR1(0, 28, lutff_5/in_0)
LEDDADDR2(0, 28, lutff_6/in_0)
LEDDADDR3(0, 28, lutff_7/in_0)
LEDDCLK(0, 29, clk)
LEDDCS(0, 28, lutff_2/in_0)
LEDDDAT0(0, 28, lutff_2/in_1)
LEDDDAT1(0, 28, lutff_3/in_1)
LEDDDAT2(0, 28, lutff_4/in_1)
LEDDDAT3(0, 28, lutff_5/in_1)
LEDDDAT4(0, 28, lutff_6/in_1)
LEDDDAT5(0, 28, lutff_7/in_1)
LEDDDAT6(0, 28, lutff_0/in_0)
LEDDDAT7(0, 28, lutff_1/in_0)
LEDDDEN(0, 28, lutff_1/in_1)
LEDDEXE(0, 28, lutff_0/in_1)
LEDDON(0, 29, slf_op_0)
PWMOUT0(0, 28, slf_op_4)
PWMOUT1(0, 28, slf_op_5)
PWMOUT2(0, 28, slf_op_6)
-
-

- -

The I2C "glitch filter" (referred to as SB_FILTER_50NS) is a seperate module from the I2C interface IP, with connections as shown below: - - - - - - - - -
SignalSB_FILTER_50NS
(25, 31, 2)		SB_FILTER_50NS
(25, 31, 3)
FILTERIN(25, 27, lutff_1/in_0)(25, 27, lutff_0/in_0)
FILTEROUT(25, 27, slf_op_2)(25, 27, slf_op_1)
ENABLE_0(25, 30, CBIT_2)(25, 30, CBIT_5)
ENABLE_1(25, 30, CBIT_3)(25, 30, CBIT_6)
ENABLE_2(25, 30, CBIT_4)(25, 30, CBIT_7)
- -