Merge pull request #3 from SymbiFlow/master

update from upstream

.gitignore

@@ -1,9 +1,23 @@
+#python
 __pycache__/
 *.pyc
+
+#Environments
 /user_environment.sh
+*..DS_Store
+
+#logs
 ispTcl.log
 ispTcl.log.*
 ispTcl.tcl
 ispTcl.tcl.*
 .ispTcl.lock
 work_*/
+
+#Editors and IDEs
+.*.d
+.*.swp
+.*.swo
+.*.swn
+.*.swm
+*.log

COPYING

@@ -11,3 +11,29 @@ ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
 WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
 ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
 OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
+
+libtrellis/include contains list_indexing_suite.h and
+set_indexing_suite.h from bond, see below license:
+
+The MIT License (MIT)
+
+Copyright (c) 2014 Microsoft
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+

README.md

@@ -14,7 +14,8 @@ Install the dependencies for Project Trellis:
  - CMake 3.5 or later
  - Boost including boost-python
  - Git
-
+ - Recent OpenOCD for device programming (`--enable-ftdi` required if building from source)
+
 Clone the Project Trellis repository and download the latest database:
 
      git clone --recursive https://github.com/SymbiFlow/prjtrellis
@@ -29,8 +30,8 @@ Out-of-tree builds are currently unsupported when coupled with `nextpnr`:
 
 Clone and install **latest git master** versions (Yosys 0.8 is not sufficient for ECP5 development) of [Yosys](https://github.com/YosysHQ/yosys)
  and [nextpnr](https://github.com/YosysHQ/nextpnr) according to their own instructions. Ensure
- to include the ECP5 architecture when building nextpnr; and point it towards your prjtrellis
- folder.
+ to include the [ECP5 architecture](https://github.com/YosysHQ/nextpnr#nextpnr-ecp5) when building nextpnr; and point it towards your prjtrellis
+ folder.  (for example: `cmake -DARCH=ecp5 -DTRELLIS_INSTALL_PREFIX=/usr .`)
 
 You should now be able to build the [examples](examples).
 

diamond.sh

@@ -17,7 +17,13 @@
 # You need to set the DIAMONDDIR environment variable to the path where you have
 # installed Lattice Diamond, unless it matches this default.
 
-diamonddir="${DIAMONDDIR:-/usr/local/diamond/3.10_x64}"
+if [ -z "$DIAMONDVER" ]; then
+	diamondver="3.10"
+else
+	diamondver="$DIAMONDVER"
+fi
+
+diamonddir="${DIAMONDDIR:-/usr/local/diamond/${diamondver}_x64}"
 export FOUNDRY="${diamonddir}/ispfpga"
 bindir="${diamonddir}/bin/lin64"
 LSC_DIAMOND=true
@@ -194,6 +200,10 @@ fi
 # make bitmap
 "$fpgabindir"/bitgen -d par_impl.ncd $BITARGS output.bit synth_impl.prf
 
+if [ -n "$JEDEC_BITSTREAM" ]; then
+"$fpgabindir"/bitgen -d par_impl.ncd -jedec output.jed synth_impl.prf
+fi
+
 # dump bitmap
 "$fpgabindir"/bstool -d output.bit > output.dump
 
@@ -226,6 +236,9 @@ fi
 if [ -z "$USE_NCL" ]; then
 cp "$2.tmp"/output.ncl "$2_out.ncl"
 fi
+if [ -n "$JEDEC_BITSTREAM" ]; then
+cp "$2.tmp"/output.jed "$2.jed"
+fi
 if [ -n "$BACKANNO" ]; then
 cp "$2.tmp"/par_impl.sdf "$2.sdf"
-fi
+fi

docs/.gitignore

@@ -1 +1,2 @@
+venv
 _build

docs/Makefile

@@ -1,13 +1,15 @@
 # Minimal makefile for Sphinx documentation
 #
 
+MAKEDIR := $(dir $(lastword $(MAKEFILE_LIST)))
+
 # You can set these variables from the command line.
-SPHINXOPTS    =
-SPHINXBUILD   = sphinx-build
-SPHINXAUTOBUILD   = sphinx-autobuild
-SPHINXPROJ    = ProjectX-Ray
-SOURCEDIR     = .
-BUILDDIR      = _build
+SPHINXOPTS      =
+SPHINXBUILD     = [ -e venv/bin/activate ] && source venv/bin/activate; sphinx-build
+SPHINXAUTOBUILD = [ -e venv/bin/activate ] && source venv/bin/activate; sphinx-autobuild
+SPHINXPROJ      = ProjectTrellis
+SOURCEDIR       = .
+BUILDDIR        = _build
 
 # Put it first so that "make" without argument is like "make help".
 help:
@@ -16,9 +18,21 @@ help:
 livehtml:
 	@$(SPHINXAUTOBUILD) -b html --ignore \*.swp --ignore \*~ $(SPHINXOPTS) "$(SOURCEDIR)" "$(BUILDDIR)/html"
 
-.PHONY: help livereload Makefile
+.PHONY: help livehtml Makefile
+
+venv:
+	rm -rf venv
+	virtualenv --python=python3 venv
+	source venv/bin/activate; pip install -r requirements.txt
+
+.PHONY: venv
+
+links:
+	@true
+
+.PHONY: links
 
 # Catch-all target: route all unknown targets to Sphinx using the new
 # "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
-%: Makefile
+%: Makefile links
 	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

docs/architecture/bitstream_format.rst

@@ -2,9 +2,9 @@ Bitstream format
 ================
 
 Some documentation on the ECP5 bitstream format is published by Lattice themselves
-in th ECP5 sysCONFIG Usage Guide (TN1260_).
+in the ECP5 sysCONFIG Usage Guide (FPGA-TN-02039_).
 
-.. _TN1260: http://www.latticesemi.com/~/media/LatticeSemi/Documents/ApplicationNotes/EH/TN1260.pdf
+.. _FPGA-TN-02039: https://www.latticesemi.com/-/media/LatticeSemi/Documents/ApplicationNotes/EH/FPGA-TN-02039-1-7-ECP5-and-ECP5-5G-sysCONFIG.pdf
 
 Basic Structure
 ----------------
@@ -55,6 +55,9 @@ Control commands seen in a typical uncompressed, unencrypted bitstream are:
 +-------------------------------+-----+--------------------------+---------------------------------------------------+
 | ``LSC_INIT_ADDRESS``          | 46  | 24 bit info: all 0       | Resets the frame address register                 |
 +-------------------------------+-----+--------------------------+---------------------------------------------------+
+| ``LSC_WRITE_ADDRESS``         | B4  | - 24 bit info: all 0     | Loads the frame address register                  |
+|                               |     | - 32 bit frame address   |                                                   |
++-------------------------------+-----+--------------------------+---------------------------------------------------+
 | ``ISC_PROGRAM_SECURITY``      | CE  | 24 bit info: all 0       | Program the security bit (prevents readback (?) ) |
 +-------------------------------+-----+--------------------------+---------------------------------------------------+
 | ``ISC_PROGRAM_USERCODE``      | C2  | - CRC bit set, 23 bits 0 | Sets the value of the USERCODE register           |
@@ -79,7 +82,7 @@ there are some setup bits:
 This is then followed by a number of frames, each in the following format:
 
  - The configuration frame itself (compressed in the case of the  ``LSC_PROG_INCR_RTI`` command),
-   such that bit 0 bit 0 of the first byte is the MSB of the frame, bit 7 of the first byte the 
+   such that bit 0 bit 0 of the first byte is the MSB of the frame, bit 7 of the first byte the
    MSB-7 and bit 0 of the last byte (if there are no dummy bits) being the LSB of the frame.
  - Any dummy bits needed to pad the frame to a whole number of bytes.
  - If the second flag is cleared (see above) a CRC-16 checksum:
@@ -91,7 +94,7 @@ This is then followed by a number of frames, each in the following format:
 The highest numbered frame in the chip is sent first.
 
 If the second flag is set there's no CRC sent in between frames but there's still one CRC-16 checksum
-after all the frames (this also covers any other commands sent before the programming command but after a CRC reset, 
+after all the frames (this also covers any other commands sent before the programming command but after a CRC reset,
 and the programming command itself.).
 
 Separate commands are used if EBR needs to be configured in the bitstream. EBR data can't use compression.
@@ -102,9 +105,9 @@ still need to be documented.
 Compression Algorithm
 ------------------------------
 
- - Before compression, the frame is left padded with zeroes (0) to make the data frame 64-bit bounded. 
- - After compressing the frame data, the resulting bits are right padded with zeroes (0) to make the data
-frame byte bounded.
+ - Before compression, the frame is left padded with zeroes (0) to make the data frame 64-bit bounded.
+ - After compressing the frame data, the resulting bits are right padded with zeroes (0)
+   to make the dataframe byte bounded.
 
 After padding, every byte in the bitstream is compressed by a simple prefix-free code with just 4 cases:
 
@@ -131,6 +134,22 @@ After padding, every byte in the bitstream is compressed by a simple prefix-free
 - The fourth case is for all remaining bytes.  In that case after a ``11`` the complete byte is copied.  For example
   byte ``11001010`` would be encoded as ``1111001010``.
 
+Partial Bitstreams
+------------------------------
+
+``LSC_WRITE_ADDRESS`` can be used to make partial bitstreams. Combined with background reconfiguration and
+the ability to reload frames glitchlessly; partial reconfiguration is possible on ECP5.
+
+``LSC_WRITE_ADDRESS`` takes a frame address; however frame addressing is not strictly linear. It has only
+been fully documented for the 45k device and is as follows:
+
+ - the first 7 bits are always between 0 and 105 (each group of 106 frames is a column)
+ - the next 5 bits are the column index within a tap region
+ - the MSBs from bit 12 onwards are the tap region index
+
+To enable loading of partial bitstreams the ``BACKGROUND_RECONFIG`` sysCONFIG option must be set. Then, to
+avoid reinitialising the whole device, instructions 0x79 with no data and 0x74 followed by 0x00 must be
+sent over JTAG before the partial bitstream data.
 
 Device-Specific Information
 ------------------------------